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 examples
  • Anatomies - For displaying and highlighting different parts of components and to display specifications
  • Stances - To visualize do's and do not's
  • CodeExamples - To view code with example

Types

Filled, primary button
Filled, primary CTA button
Outlined, secondary button
Outlined, text button
Filled, info button 
<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

Do not use two or more primary buttons together
Only use one primary button per view 
<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:

Secondary button
  1. Text label, Box is inverse filled and with outline
Secondary button
  1. Text label, Box is inverse filled and with outline
  2. 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:

Button

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>

Table of Contents

Edit this section, Opens in new window
Contact us, Opens in new window