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:

  • .if.types - For displaying different variants, types and examples
  • .if.anatomies - For displaying and highlighting different parts of components and to display specifications
  • .if.stances - To visualize do's and do not's
Types
Filled, primary button
Filled, primary CTA button
Outlined, secondary button
Outlined, text button
Filled, info button
<div class="if types">
  <figure class="if type">
    <div class="if example airy highlight">
      <button class="if button primary">Primary button</button>
    </div>
    <figcaption class="if description">Filled, primary button</figcaption>
  </figure>
  <figure class="if type">
    <div class="if example airy highlight">
      <button class="if button primary large">CTA button</button>
    </div>
    <figcaption class="if description">Filled, primary CTA button</figcaption>
  </figure>
  <figure class="if type">
    <div class="if example airy light">
      <button class="if button secondary">Secondary button</button>
    </div>
    <figcaption class="if description">Outlined, secondary button</figcaption>
  </figure>
  <figure class="if type">
    <div class="if example airy light">
      <button class="if button text">Tertiary button</button>
    </div>
    <figcaption class="if description">Outlined, text button</figcaption>
  </figure>
  <figure class="if type">
    <div class="if example airy highlight">
      <button class="if button info">Info button</button>
    </div>
    <figcaption class="if description">Filled, info button</figcaption>
  </figure>
</div>
Stances
Do not use two or more primary buttons together
Only use one primary button per view
<div class="if stances">
  <figure style="height: 20rem;" class="if stance bad">
    <div class="if example">
      <button type="button" class="if button primary">No</button>
      <button type="button" class="if button primary">Yes</button>
    </div>
    <figcaption class="if description">
      Do not use two or more primary buttons together
    </figcaption>
  </figure>
  <figure style="height: 20rem;" class="if stance good">
    <div class="if example">
      <button type="button" class="if button secondary">No</button>
      <button type="button" class="if button primary">Yes</button>
    </div>
    <figcaption class="if description">
      Only use one primary button per view
    </figcaption>
  </figure>
</div>

Helper classes

Badges

.if.tryme - Used to indicate that user can interact with the examples
.if.spec-missing - Used to indicate that we do not have the specification for this component or type or state
<div class="if types">
  <figure class="if type tryme">
    <div class="if example airy light"> <button class="if button">Button</button> </div>
    <figcaption class="if description">
      <code class="language-css">.if.tryme</code> - Used to indicate that user can interact with the examples
    </figcaption>
  </figure>
  <figure class="if type spec-missing">
      <div class="if example airy light"> <button class="if button">Button</button> </div>
      <figcaption class="if description">
      <code class="language-css">.if.spec-missing</code> - Used to indicate that we do not have the specification for this component or type or state
      </figcaption>
    </figure>
</figure>
</div>

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). We use @phun-ky/responsive-documentation-examples for this.

Write a section like this in a documentation file, for example docs/responsive.md:

First, create a template holder in docs/responsive.md. This will contain the example you want to display:

# Responsive examples

<div data-responsive data-responsive-id="button" class="sg hidden">
  <button class="if button">A button</button>
</div>

Then add the required iframe for this to work:

<iframe id="button-responsive-mobile" class="sg responsive"></iframe>

Or

<iframe id="button-responsive-tablet-portrait" class="sg responsive"></iframe>

Or

<iframe id="button-responsive-tablet-landscape" class="sg responsive"></iframe>

Or

<iframe id="button-responsive-desktop" class="sg responsive"></iframe>

And you're done! The documentation site includes a script that will automatically generate the responsive example in the iframe.

The file docs/responsive.md should look somewhat similar to this:

### Responsive examples

<div data-responsive data-responsive-id="button" class="sg hidden">
  <button class="if button">A button</button>
</div>
<div class="if anatomies">
<figure class="if anatomy responsive iphone">
<div class="if example">
<div>
<iframe id="button-responsive-tablet-landscape" class="sg responsive"></iframe>
</div>
</div>
<figcaption class="if description">
<span class="if title">Title</span>
</figcaption>
</figure>
</div>
Title

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

<div class="if anatomies">
<figure class="if anatomy" data-anatomy-section>
<div class="if example airy">
<button class="if button">Secondary button</button>
</div>
<figcaption class="if description">
<span class="if title">Secondary button</span>

<ol class="if anatomy-grid">
<li class="if">
Text label, Box is inverse filled and with outline
</li>
</ol>

</figcaption>
</figure>
<figure class="if anatomy" data-anatomy-section>
<div class="if example airy">
<button class="if button"><span class="if icon ui edit blue"></span>Secondary button</button>
</div>
<figcaption class="if description">
<span class="if title">Secondary button</span>
<ol class="if anatomy-grid">
<li class="if">Text label, Box is inverse filled and with outline</li>
<li class="if">With icon</li>
</ol>
</figcaption>
</figure>
</div>

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/implementation.md:

### Implementation

```html
<button class="if button [primary|secondary|info]">A button</button>
```

The above code will look something like this:

Implementation

<button class="if button [primary|secondary|info]">A button</button>

Table of Contents

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