Documenting
To generate and create documentation, we use Gatsby. This guide will not cover exactly how that works, but how we create our documentation.
Frontmatter
To make sure the markdown files are read and sourced correctly by Gatsby, you need to add frontmatter in the top of your markdown files:
---
title: 'Button'
order: 1
category: 'develop'
subCategory: 'button'
componentName: 'button'
customPath: '/components/actions/button'
---
Prop | Value | Type | Required | Notes |
---|---|---|---|---|
title | The title of the page | String | ✓ | |
order | The order that it should have on a page | Number | ✓ | |
tags | List of tags to describe the document | Array | no | |
componentName | The name of the component, lowercase | String | no | For components only |
category | The category of the page, lowercase | String | ✓ | |
subCategory | The subcategory of the page, lowercase | String | no | |
customPath | The desired path, used to group files and for navigation, lowercase | String | ✓ |
Basics
Documentation is key to understand and to use the design system. We aim for clarity and consistency. After all, the documentation is read by humans. Developers, UX-designers, graphical designers and others.
The documentation should be guiding, not too direct. It should allow for further development of the design. However, the documentation should be so concise that there are no misconceptions.
Decorators
We use different type of decorators for our examples:
Types
- For displaying different variants, types and examplesAnatomies
- For displaying and highlighting different parts of components and to display specificationsStances
- To visualize do's and do not'sCodeExamples
- To view code with example
Types
<Types>
<Type>
<Example>
<button class="if button primary">Primary button</button>
</Example>
<Description>
<span class="ids-doc title">Primary button</span>
</Description>
</Type>
</Types>
Stances
<Stances>
<Bad>
<Example>
<button type="button" class="if button primary">
No
</button>
<button type="button" class="if button primary">
Yes
</button>
</Example>
<Description>Do not use two or more primary buttons together</Description>
</Bad>
<Good>
<Example>
<button type="button" class="if button secondary">
No
</button>
<button type="button" class="if button primary">
Yes
</button>
</Example>
<Description>Only use one primary button per view</Description>
</Good>
</Stances>
Examples
Examples are crucial to the documentation. It gives us the possibility to communicate how a component should look like, how it should behave and what it can and cannot do.
Responsive
If you want, you can add responsive examples, how your component would look like in certain viewports (devices).
Write a section like this in a documentation file, for example docs/responsive.mdx
:
First, create a template holder in docs/responsive.mdx
. This will contain the example you want to display, and add
desired device:
<Types>
<Type>
<Example device="iphone">
<button class="if button">A button</button>
</Example>
</Type>
</Types>
Available devices is:
samsung
tablet
fluid
iphone
mobile
Types
Use the type decorator to indicate and communicate that there are different types of a component.
States
Use the state decorator to indicate and communicate that there are different states of a component.
Annotation
To clarify which element inside a component is what, and to pin point important parts of a component, we use @phun-ky/speccer.
Write a section like this in a documentation file, for example: docs/anatomy.md
:
## Anatomy
<Anatomies>
<Anatomy>
<Example>
<button class="if button">Secondary button</button>
</Example>
<Description>
<span class="ids-doc title">Secondary button</span>
<ol class="if anatomy-grid">
<li class="if">
Text label, Box is inverse filled and with outline
</li>
</ol>
</Description>
</Anatomy>
</Anatomies>
And add data-anatomy
attributes to the button tags, like so:
-<button class="if button">Secondary button</button>
+<button data-anatomy="outline top" class="if button">Secondary button</button>
…
-<button class="if button">
- <span class="if icon ui edit blue"></span>
- Secondary button
-</button>
+<button data-anatomy="outline top" class="if button">
+ <span data-anatomy="outline bottom" class="if icon ui edit blue"></span>
+ Secondary button
+</button>
The result will look something like this:
- Text label, Box is inverse filled and with outline
- Text label, Box is inverse filled and with outline
- With icon
For full documentation on how to use @phun-ky/speccer, see the README.md.
Specifications
Sometimes it is needed to be very clear on what margins and paddings a component have. It is not easy to communicate what this is visually, so we use @phun-ky/speccer for this.
Write a section like this in a documentation file, for example: docs/specs.md
:
## Specs
<div class="if anatomies">
<figure class="if anatomy">
<div class="if example airy light">
<button type="button" class="if button primary">Button</button>
<button style="margin-left: 1rem;" type="button" class="if button primary">Button</button>
<button style="margin-left: 1rem;" type="button" class="if button primary">Button</button>
</div>
<figcaption class="if description">
<span class="if title">Button</span>
</figcaption>
</figure>
</div>
Then update it with the tags you want to use to display specs. In this example, we want to show margin and padding for
the first button, then the width of the second, and then the height with the third. The tags used, in order
are: data-speccer
, data-speccer-measure="width bottom"
and data-speccer-measure="height right"
:
## Specs
<div class="if anatomies">
<figure class="if anatomy">
<div class="if example airy light">
<button type="button" class="if button primary" data-speccer>Button</button>
<button style="margin-left: 1rem;" type="button" class="if button primary" data-speccer-measure="width bottom">Button</button>
<button style="margin-left: 1rem;" type="button" class="if button primary" data-speccer-measure="height right">Button</button>
</div>
<figcaption class="if description">
<span class="if title">Button</span>
</figcaption>
</figure>
</div>
Result
The result should be something like this:
For full documentation on how to use @phun-ky/speccer, see the README.md.
Implementation
Always document how the user can implement this component. Write a section like this in a documentation file, for
example docs/css/usage.md
:
---
title: 'Usage'
order: 2
category: 'components'
subCategory: 'button'
componentName: 'button'
customPath: '/components/actions/button/css'
---
<CodeExamples>
<CodeExample>
<Example>
<button class="if button">A button</button>
</Example>
<CodeDescription>
<CodeBlock>
```html
<button class="if button [primary|secondary|info]">A button</button>
```
</CodeBlock>
</CodeDescription>
</CodeExample>
</CodeExamples>