Skip to content

Commit 8be97c2

Browse files
aweellaweell
authored
Merge pull request #642 from dxc-technology/contributing-docs
[Contributing] Add docs to DS guidelines
2 parents 22c7468 + 390c786 commit 8be97c2

16 files changed

+802
-0
lines changed

‎guidelines/catalog.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,5 +138,23 @@
138138
"key": "wizard",
139139
"name": "Wizard"
140140
}
141+
],
142+
"contributing": [
143+
{
144+
"key": "overview",
145+
"name": "Overview"
146+
},
147+
{
148+
"key": "content",
149+
"name": "Content"
150+
},
151+
{
152+
"key": "image",
153+
"name": "Image"
154+
},
155+
{
156+
"key": "design",
157+
"name": "Design"
158+
}
141159
]
142160
}

‎guidelines/contributing/content/README.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# Content
2+
3+
## Markdown
4+
5+
Our documentation pages are written in markdown. [Check the markdown guide for the basic syntax](https://www.markdownguide.org/basic-syntax/).
6+
7+
## Writing content
8+
9+
* Keep sentences and paragraphs short and focused.
10+
* Be clear and concise by removing unnecessary words.
11+
* Use sentence case for everything, including component names
12+
13+
## Sections
14+
15+
Our components documentation is divided in 4 main different sections:
16+
17+
* **Introduction**: Brief description of the component.
18+
* **Usage**: How the component should be used.
19+
* **Anatomy**: All the individual elements that are part of the component.
20+
* **Design specs**: How the component is built.
21+
22+
Other sections to consider adding to a component documentation:
23+
24+
* States
25+
* Variants
26+
* Placement and aligment
27+
* Behavior and interaction
28+
* Content
29+
* Accessibility
30+
31+
You can check out our [templates](https://github.com/dxc-technology/halstack-style-guide/blob/contribution-content/contributing/template.md) for component and patterns documentation.
32+
33+
### Creating hierarchy
34+
35+
All documentation pages should follow the same hierarchy:
36+
37+
| Item | Purpose | Markdown syntax |
38+
| ---------- | ----------------------------- | --------------- |
39+
| `h1` | Component or principle name | `#` |
40+
| `h2` | General sections | `##` |
41+
| `h3` | Subsections | `###` |
42+
| `h4`, `h5` | Any needed subdivisions | `####`, `#####` |
43+
44+
45+
The title and sections for every page follow the same syntax across all our documentation. You can check a more complete [heading markdown syntax guide](https://www.markdownguide.org/basic-syntax/#headings). Below you can find an example of how one of our component documentation hierarchy is built:
46+
47+
```
48+
49+
# Select
50+
## Usage
51+
## States
52+
### Text-input
53+
### Options list
54+
## Anatomy
55+
## Design specs
56+
## Accesibility
57+
58+
```
59+
_Example of a component documentation page headings hierarchy_
60+
61+
### Heading anchors
62+
63+
In order to provide a way to navigate through the documentation pages anchor links are used.
64+
65+
* Anchor links are placed after the title of the component and the general description
66+
* The anchors only should be created for second-level headings (`##`)
67+
68+
```
69+
* [Usage](#usage)
70+
* [Formatting](#formatting)
71+
* [Anatomy](#anatomy)
72+
* [Placement and alignment](#placement-and-alignment)
73+
* [Behavior and interaction](#behavior-and-interaction)
74+
* [Content](#content)
75+
* [Design specifications](#design-specifications)
76+
* [Accessibility](#accessibility)
77+
```
78+
_Example of an anchor links section_
79+
80+
### Bottom links
81+
82+
Every page should have a dedicated section at the bottom with related links, in this section are included:
83+
84+
* **Angular CDK component**: link to the latest released angular component. [Angular CDK documentation](https://developer.dxc.com/tools/angular/)
85+
* **React CDK component**: link to the latest released react component. [React CDK documentation](https://developer.dxc.com/tools/react/)
86+
* **Adobe XD component**: link to the latest Adobe XD view component page
87+
* **Edit this page in GitHub**: link to the `README.md` of the page in the master branch
88+
89+
Use the following template to add the “links and references“ section to any documentation page:
90+
91+
```
92+
93+
## Links and references
94+
95+
* [Angular CDK component]()
96+
* [React CDK component]()
97+
* [Adobe XD component]()
98+
99+
_________________________
100+
101+
[Edit this page on GitHub]()
102+
103+
```
104+
105+
_Example of the “links and references“ section_
106+
107+
## Anatomy
108+
109+
The anatomy section helps users and developers to understand the building blocks of a component and provides information abour the naming of the elements. This section basically consists of an image and a list of elements.
110+
111+
* Number the anatomy markers from left to right and from top to bottom
112+
* When an element is optional, point it out in its list reference
113+
* When choosing the component image, try to provide the component that has all the possible elements present, when it is not possible, use two examples
114+
115+
Use the following template to add the section:
116+
117+
```
118+
## Anatomy
119+
120+
![Image Alt text]()
121+
122+
1. Element 01
123+
2. Element 02 _(Optional)_
124+
3. Element 03
125+
```
126+
_Example of the “anatomy“ section_
127+
128+
## Design specifications
129+
130+
When writing design specifications consider the following:
131+
132+
* Add a [support image](https://developer.dxc.com/design/guidelines/contributing/images) as the first item of the component specifications.
133+
* Subdivide the component specs regarding the property (e.g. color, size, typography)
134+
135+
### Spec tables
136+
137+
Design specifications are written mainly based on tables, in order to be consistent across all our documentation pages:
138+
139+
* Use lowercase when referencing HEX values (#ffffff instead of #FFFFFF)
140+
* Use scape backticks for property `items` and `tokens`
141+
* Use sentence case (except items contained by space backticks)
142+
* Lenght values should include both pixels and rems and follow the naming convention #px/#rem (replace rems for the more convenient relative unit)
143+
144+
145+
Example of a component specs table:
146+
147+
```
148+
149+
| Property | Element | Core token | Value |
150+
| :-------------- | :--------------- | :---------- | :-------- |
151+
| `property-1` | Element-1 | `token-1` | value-1 |
152+
| `property-2` | Element-2 | `token-2` | value-2 |
153+
| `property-3` | Element-3 | `token-3` | value-3 |
154+
155+
```
156+
If the component has specific tokens for the properties that affect the elements listed use them instead:
157+
158+
```
159+
160+
| Component token | Element | Core token | Value |
161+
| :---------------- | :--------------- | :---------- | :-------- |
162+
| `token-1` | Element-1 | `token-1` | value-1 |
163+
| `token-2` | Element-2 | `token-2` | value-2 |
164+
| `token-3` | Element-3 | `token-3` | value-3 |
165+
166+
```
167+
168+
Appart from the component specs, the principles and layout-patterns pages also should contain specification tables.
169+
170+
Example of a core tokens specs table:
171+
172+
```
173+
174+
| Token | Description | Property | Value |
175+
| ----------- | -------------------- | -------------- | --------- |
176+
| `token-1` | _Brief description_ | `property-1` | value-1 |
177+
| `token-2` | _Brief description_ | `property-2` | value-2 |
178+
| `token-3` | _Brief description_ | `property-3` | value-3 |
179+
180+
```
181+
182+
## Accessibility
183+
184+
The accessibility section provides all the resources needed in order to build accessible components, we follow the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/TR/WCAG22/) and [WAI-ARIA](https://www.w3.org/TR/wai-aria-1.2/) guidelines.
185+
186+
Every component documentation page should provide:
187+
188+
* All the Success Criterion<sup>1</sup> that may apply to the component behavior
189+
* The WAI-ARIA design pattern and example
190+
191+
192+
1: Every Succes Criterion should be linked to their reference inside [Understanding WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/) document. Learn more about Success criteria in the [WCAG Understanding conformance page](https://www.w3.org/WAI/WCAG21/Understanding/conformance#levels).
193+
194+
### Referencing and linking
195+
196+
When referencing and linking to guidelines or other technical documents ensure you are following the [W3C recommendation](https://www.w3.org/WAI/standards-guidelines/linking/:)
197+

0 commit comments

Comments
 (0)