@workday/canvas-kit-docs 9.1.11 → 9.1.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
<Meta
|
|
2
|
+
title="Guides/Documentation Guidelines"
|
|
3
|
+
parameters={{
|
|
4
|
+
viewMode: 'docs',
|
|
5
|
+
previewTabs: {
|
|
6
|
+
canvas: {hidden: true},
|
|
7
|
+
},
|
|
8
|
+
}}
|
|
9
|
+
/>
|
|
10
|
+
|
|
11
|
+
# Documentation Guidelines
|
|
12
|
+
|
|
13
|
+
## Introduction
|
|
14
|
+
|
|
15
|
+
### Writing Style
|
|
16
|
+
|
|
17
|
+
Google provides [helpful resources](https://developers.google.com/tech-writing/overview) for how to
|
|
18
|
+
write technical documentation. We highly recommend you familiarize yourself with their materials
|
|
19
|
+
when authoring documentation for Canvas Kit.
|
|
20
|
+
|
|
21
|
+
### Conventions
|
|
22
|
+
|
|
23
|
+
Placeholder content throughout this document is enclosed in brackets as `[placeholder]`. For
|
|
24
|
+
example, if you were writing component documentation for `Tabs`, you would replace:
|
|
25
|
+
|
|
26
|
+
```tsx
|
|
27
|
+
import {[Component]} from '@workday/canvas-kit-[preview-|labs-]react/[component]';
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
with:
|
|
31
|
+
|
|
32
|
+
```tsx
|
|
33
|
+
import {Tabs} from '@workday/canvas-kit-react/tabs';
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Component Documentation
|
|
37
|
+
|
|
38
|
+
Every component MDX (with a few [exceptions](#component-families)) should follow the structure
|
|
39
|
+
outlined below.
|
|
40
|
+
|
|
41
|
+
````md
|
|
42
|
+
<!--
|
|
43
|
+
Import components which will be used to render documentation in the MDX file.
|
|
44
|
+
The Specifications import is optional; only include it if the Specifications
|
|
45
|
+
section exists (see below).
|
|
46
|
+
-->
|
|
47
|
+
import {Specifications, SymbolDoc} from '@workday/canvas-kit-docs';
|
|
48
|
+
|
|
49
|
+
<!--
|
|
50
|
+
Import the component so we can pass it into the Storybook Meta tag (see
|
|
51
|
+
below).
|
|
52
|
+
-->
|
|
53
|
+
import {[Component]} from '@workday/canvas-kit-[preview-|labs-]react/[component]';
|
|
54
|
+
|
|
55
|
+
<!-- Import component examples -->
|
|
56
|
+
import Basic from './examples/Basic';
|
|
57
|
+
import AnotherExample from './examples/AnotherExample';
|
|
58
|
+
import ...
|
|
59
|
+
|
|
60
|
+
<!--
|
|
61
|
+
Use the Storybook Meta tag to designate where to display the component in the
|
|
62
|
+
Storybook navigation hierarchy. The title prop specifies where to show the
|
|
63
|
+
component in the hierarchy. The component prop is required to get the component
|
|
64
|
+
to show up at the end of that path.
|
|
65
|
+
-->
|
|
66
|
+
|
|
67
|
+
# Canvas Kit [Component]
|
|
68
|
+
|
|
69
|
+
Short description of Component.
|
|
70
|
+
|
|
71
|
+
## Installation
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
yarn add @workday/canvas-kit-[preview-|labs-]react
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
<!--
|
|
78
|
+
The Usage section should be a list of examples of how to use the component.
|
|
79
|
+
Aside from having a Basic Example, there are no set rules on how many examples
|
|
80
|
+
to include for a given component. Try to include enough examples to illustrate
|
|
81
|
+
all common use cases and anything which may not be obvious based on the
|
|
82
|
+
component API.
|
|
83
|
+
-->
|
|
84
|
+
## Usage
|
|
85
|
+
|
|
86
|
+
<!--
|
|
87
|
+
Every component should have a basic example as its first example in the Usage
|
|
88
|
+
section. Title the section "Basic Example" for consistency.
|
|
89
|
+
-->
|
|
90
|
+
### Basic Example
|
|
91
|
+
|
|
92
|
+
Description of the Basic Example.
|
|
93
|
+
|
|
94
|
+
<!--
|
|
95
|
+
Every example should include an ExampleCodeBlock which renders the example
|
|
96
|
+
along with its associated code.
|
|
97
|
+
-->
|
|
98
|
+
<ExampleCodeBlock code={Basic} />
|
|
99
|
+
|
|
100
|
+
<!--
|
|
101
|
+
Feel free to include supplemental or follow-up information about the example
|
|
102
|
+
underneath the ExampleCodeBlock (if necessary).
|
|
103
|
+
-->
|
|
104
|
+
More information about the Basic Example.
|
|
105
|
+
|
|
106
|
+
### Another Example
|
|
107
|
+
|
|
108
|
+
Description of Another Example.
|
|
109
|
+
|
|
110
|
+
<ExampleCodeBlock code={AnotherExample} />
|
|
111
|
+
|
|
112
|
+
### More Examples...
|
|
113
|
+
|
|
114
|
+
<!--
|
|
115
|
+
The SymbolDoc component will generate the entire Component API section using
|
|
116
|
+
the component's JSDocs. This includes descriptions and props tables for the
|
|
117
|
+
component, as well as its subcomponents if it's a compound component.
|
|
118
|
+
Documentation for the model will also be included if the component has a model.
|
|
119
|
+
-->
|
|
120
|
+
## Component API
|
|
121
|
+
|
|
122
|
+
<!--
|
|
123
|
+
The fileName prop is used to disambiguate between components which exist in
|
|
124
|
+
multiple Canvas Kit packages.
|
|
125
|
+
-->
|
|
126
|
+
<SymbolDoc name="[Component]" fileName="/[preview-|labs-]react/" />
|
|
127
|
+
|
|
128
|
+
<!--
|
|
129
|
+
The Specifications section is optional. Only include it if the component has
|
|
130
|
+
Cypress integration tests (i.e., a spec.ts file in the cypress/integration
|
|
131
|
+
folder).
|
|
132
|
+
-->
|
|
133
|
+
## Specifications
|
|
134
|
+
|
|
135
|
+
<Specifications file="[Component].spec.ts" name="[Component]" />
|
|
136
|
+
````
|
|
137
|
+
|
|
138
|
+
> **Note:** Refer to [Tabs](/components/containers/tabs/) and [Modal](/components/popups/modal/) for
|
|
139
|
+
> examples of how to write well-structured component documentation.
|
|
140
|
+
|
|
141
|
+
### Component Families
|
|
142
|
+
|
|
143
|
+
Occasionally, you may want to document multiple top-level components (i.e., _not_ subcomponents) on
|
|
144
|
+
a single page. For example, we document `PrimaryButton`, `SecondaryButton`, `TertiaryButton`, and
|
|
145
|
+
`DeleteButton` on a single page for all [Button](/components/buttons/button/) components since
|
|
146
|
+
they're all similar.
|
|
147
|
+
|
|
148
|
+
Upon identifying a `ComponentFamily` name (e.g., `Button`) for the collection of related components,
|
|
149
|
+
you'll then follow the same document structure defined above with slight modifications.
|
|
150
|
+
|
|
151
|
+
````md
|
|
152
|
+
<!-- Only import SymbolDescription if necessary (see below) -->
|
|
153
|
+
import {Specifications, SymbolDoc, SymbolDescription} from '@workday/canvas-kit-docs';
|
|
154
|
+
|
|
155
|
+
<!-- Import component examples -->
|
|
156
|
+
import Component1Example from './examples/Component1Example';
|
|
157
|
+
import Component2Example from './examples/Component2Example';
|
|
158
|
+
import ...
|
|
159
|
+
|
|
160
|
+
<!--
|
|
161
|
+
We are unable to use the component prop here since a component family
|
|
162
|
+
represents multiple components.
|
|
163
|
+
-->
|
|
164
|
+
|
|
165
|
+
# Canvas Kit [ComponentFamily]
|
|
166
|
+
|
|
167
|
+
Short description of ComponentFamily.
|
|
168
|
+
|
|
169
|
+
## Installation
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
yarn add @workday/canvas-kit-[preview-|labs-]react
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
<!--
|
|
176
|
+
Unlike the Usage section for a single component, the Usage section for a
|
|
177
|
+
component family will not have a Basic Example. Instead, it will have one
|
|
178
|
+
section for each component in the family; each section will contain one or
|
|
179
|
+
more examples for that particular component.
|
|
180
|
+
-->
|
|
181
|
+
## Usage
|
|
182
|
+
|
|
183
|
+
<!--
|
|
184
|
+
Each section is named after the component.
|
|
185
|
+
-->
|
|
186
|
+
### Component1
|
|
187
|
+
|
|
188
|
+
<!--
|
|
189
|
+
Unlike SymbolDoc which renders the entire component API for a given component,
|
|
190
|
+
SymbolDescription will only render the JSDoc description for that component.
|
|
191
|
+
When writing an example for a component within a family, you _may_ (optional)
|
|
192
|
+
want to render its SymbolDescription alongside the example description to
|
|
193
|
+
reduce duplicate content between the Usage and Component API sections.
|
|
194
|
+
-->
|
|
195
|
+
<SymbolDescription name="Component1" fileName="/[preview-|labs-]react/" />
|
|
196
|
+
|
|
197
|
+
Description of Component1Example.
|
|
198
|
+
|
|
199
|
+
<ExampleCodeBlock code={Component1Example} />
|
|
200
|
+
|
|
201
|
+
More information about Component1Example.
|
|
202
|
+
|
|
203
|
+
<!--
|
|
204
|
+
If necessary, you may add more examples for a single component within that
|
|
205
|
+
component's Usage section.
|
|
206
|
+
-->
|
|
207
|
+
#### Another Component1 Example
|
|
208
|
+
|
|
209
|
+
### Component2
|
|
210
|
+
|
|
211
|
+
Description of Component2Example.
|
|
212
|
+
|
|
213
|
+
<ExampleCodeBlock code={Component2Example} />
|
|
214
|
+
|
|
215
|
+
### More Components...
|
|
216
|
+
|
|
217
|
+
<!--
|
|
218
|
+
You may include more examples at the end of the Usage section for examples
|
|
219
|
+
which are not comopnent-specific and apply to every component in the family.
|
|
220
|
+
-->
|
|
221
|
+
### More Examples...
|
|
222
|
+
|
|
223
|
+
<!--
|
|
224
|
+
Unlike the Component API section for a single component, the Component API
|
|
225
|
+
section for a component family will include multiple SymbolDocs, one for each
|
|
226
|
+
component in the family.
|
|
227
|
+
-->
|
|
228
|
+
## Component API
|
|
229
|
+
|
|
230
|
+
<SymbolDoc name="[Component1]" fileName="/[preview-|labs-]react/" />
|
|
231
|
+
<SymbolDoc name="[Component2]" fileName="/[preview-|labs-]react/" />
|
|
232
|
+
...
|
|
233
|
+
|
|
234
|
+
<!--
|
|
235
|
+
Typically, all components within a family will share the same specifications
|
|
236
|
+
file.
|
|
237
|
+
-->
|
|
238
|
+
## Specifications
|
|
239
|
+
|
|
240
|
+
<Specifications file="[ComponentFamily].spec.ts" name="[ComponentFamily]" />
|
|
241
|
+
````
|
|
242
|
+
|
|
243
|
+
> **Note:** Refer to [Button](/components/buttons/button/) for an example of how to write
|
|
244
|
+
> well-structured component family documentation.
|
|
@@ -1,12 +1,5 @@
|
|
|
1
1
|
import {Specifications, SymbolDoc, SymbolDescription} from '@workday/canvas-kit-docs';
|
|
2
2
|
|
|
3
|
-
import {
|
|
4
|
-
PrimaryButton,
|
|
5
|
-
SecondaryButton,
|
|
6
|
-
TertiaryButton,
|
|
7
|
-
DeleteButton,
|
|
8
|
-
} from '@workday/canvas-kit-react/button';
|
|
9
|
-
|
|
10
3
|
import Primary from './examples/Primary';
|
|
11
4
|
import PrimaryInverse from './examples/PrimaryInverse';
|
|
12
5
|
import Secondary from './examples/Secondary';
|
|
@@ -35,8 +28,7 @@ yarn add @workday/canvas-kit-react
|
|
|
35
28
|
|
|
36
29
|
<SymbolDescription name="PrimaryButton" fileName="/react/" />
|
|
37
30
|
|
|
38
|
-
|
|
39
|
-
the size, add an icon, etc.
|
|
31
|
+
The example below shows multiple instances of a `PrimaryButton` with various icon configurations.
|
|
40
32
|
|
|
41
33
|
<ExampleCodeBlock code={Primary} />
|
|
42
34
|
|
|
@@ -46,14 +38,12 @@ when you need to place a Primary Button on a dark or colorful background such as
|
|
|
46
38
|
|
|
47
39
|
<ExampleCodeBlock code={PrimaryInverse} />
|
|
48
40
|
|
|
49
|
-
#### Component API
|
|
50
|
-
|
|
51
|
-
<SymbolDoc name="PrimaryButton" fileName="/react/" hideHeading hideDescription headingStart={4} />
|
|
52
|
-
|
|
53
41
|
### SecondaryButton
|
|
54
42
|
|
|
55
43
|
<SymbolDescription name="SecondaryButton" fileName="/react/" />
|
|
56
44
|
|
|
45
|
+
The example below shows multiple instances of a `SecondaryButton` with various icon configurations.
|
|
46
|
+
|
|
57
47
|
<ExampleCodeBlock code={Secondary} />
|
|
58
48
|
|
|
59
49
|
Secondary Buttons also have an `inverse` variant. Use this when you need to place a Secondary Button
|
|
@@ -61,14 +51,12 @@ on a dark or colorful background such as `blueberry400`.
|
|
|
61
51
|
|
|
62
52
|
<ExampleCodeBlock code={SecondaryInverse} />
|
|
63
53
|
|
|
64
|
-
#### Component API
|
|
65
|
-
|
|
66
|
-
<SymbolDoc name="SecondaryButton" fileName="/react/" hideHeading hideDescription headingStart={4} />
|
|
67
|
-
|
|
68
54
|
### TertiaryButton
|
|
69
55
|
|
|
70
56
|
<SymbolDescription name="TertiaryButton" fileName="/react/" />
|
|
71
57
|
|
|
58
|
+
The example below shows multiple instances of a `TertiaryButton` with various icon configurations.
|
|
59
|
+
|
|
72
60
|
<ExampleCodeBlock code={Tertiary} />
|
|
73
61
|
|
|
74
62
|
Tertiary Buttons also have an `inverse` variant. Use this when you need to place a Tertiary Button
|
|
@@ -76,20 +64,12 @@ on a dark or colorful background such as `blueberry400`.
|
|
|
76
64
|
|
|
77
65
|
<ExampleCodeBlock code={TertiaryInverse} />
|
|
78
66
|
|
|
79
|
-
#### Component API
|
|
80
|
-
|
|
81
|
-
<SymbolDoc name="TertiaryButton" fileName="/react/" hideHeading hideDescription headingStart={4} />
|
|
82
|
-
|
|
83
67
|
### DeleteButton
|
|
84
68
|
|
|
85
69
|
<SymbolDescription name="DeleteButton" fileName="/react/" />
|
|
86
70
|
|
|
87
71
|
<ExampleCodeBlock code={Delete} />
|
|
88
72
|
|
|
89
|
-
#### Component API
|
|
90
|
-
|
|
91
|
-
<SymbolDoc name="DeleteButton" fileName="/react/" hideHeading hideDescription headingStart={4} />
|
|
92
|
-
|
|
93
73
|
### Custom Styles
|
|
94
74
|
|
|
95
75
|
We understand that there are instances in which consumers might need to adjust styles for specific
|
|
@@ -106,6 +86,13 @@ semantic element - usually an `<a>`, or a `<button>`. This should be done with c
|
|
|
106
86
|
best accessibility. Generally, `<button>` elements should be used for actions, and `<a>` elements
|
|
107
87
|
should be used for navigation.
|
|
108
88
|
|
|
89
|
+
## Component API
|
|
90
|
+
|
|
91
|
+
<SymbolDoc name="PrimaryButton" fileName="/react/" />
|
|
92
|
+
<SymbolDoc name="SecondaryButton" fileName="/react/" />
|
|
93
|
+
<SymbolDoc name="TertiaryButton" fileName="/react/" />
|
|
94
|
+
<SymbolDoc name="DeleteButton" fileName="/react/" />
|
|
95
|
+
|
|
109
96
|
## Specifications
|
|
110
97
|
|
|
111
98
|
<Specifications file="Button.spec.ts" name="Button" />
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@workday/canvas-kit-docs",
|
|
3
|
-
"version": "9.1.
|
|
3
|
+
"version": "9.1.13",
|
|
4
4
|
"description": "Documentation components of Canvas Kit components",
|
|
5
5
|
"author": "Workday, Inc. (https://www.workday.com)",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -44,9 +44,9 @@
|
|
|
44
44
|
"dependencies": {
|
|
45
45
|
"@emotion/styled": "^11.6.0",
|
|
46
46
|
"@storybook/csf": "0.0.1",
|
|
47
|
-
"@workday/canvas-kit-labs-react": "^9.1.
|
|
48
|
-
"@workday/canvas-kit-preview-react": "^9.1.
|
|
49
|
-
"@workday/canvas-kit-react": "^9.1.
|
|
47
|
+
"@workday/canvas-kit-labs-react": "^9.1.13",
|
|
48
|
+
"@workday/canvas-kit-preview-react": "^9.1.13",
|
|
49
|
+
"@workday/canvas-kit-react": "^9.1.13",
|
|
50
50
|
"@workday/canvas-system-icons-web": "^3.0.0",
|
|
51
51
|
"markdown-to-jsx": "^6.10.3",
|
|
52
52
|
"ts-node": "^10.9.1"
|
|
@@ -57,5 +57,5 @@
|
|
|
57
57
|
"mkdirp": "^1.0.3",
|
|
58
58
|
"typescript": "4.2"
|
|
59
59
|
},
|
|
60
|
-
"gitHead": "
|
|
60
|
+
"gitHead": "803e504ebbca7db32a38d6bdf86a93752aa3da1a"
|
|
61
61
|
}
|