slides.oddbird.net/rws/smashing/docs/

Integrated Documentation

@ Smashing Online

I’m Sorry, But First Rule of Design Systems

If They’re Not Communicated, They Don’t Exist

If They’re Not Integrated, They Won’t Exist

Potentially Cross- Application & Platform

My job is to make sure the system is modular and flexible enough to be used in any number of unpredictable ways.

– Mina Markham, Pantsuit

Design Systems Represent Integration

Design & Code & Process & Tools & Docs & ???

Design Systems

Style Guides + Tool Kits + Component Libraries + ???

You are not MailForce or InstaFace

(unless you are)

How do you sell it To Clients or Bosses?

Since OddBird thinks about handoff from the beginning, maintenance has been super easy. For example, 100% unit test coverage was a given. I never had to ask for it.

– Sara Taillon, CTO at ORCAS

Perceivable,
Operable,
Understandable,
Robust

(Learn To Test)

Accessibility is For Everyone

Along any number of spectrums

Document Accessible Use Cases

Along with uses to avoid

Continuous Integration Accurate > Complete

Continuous Integration Maintained > Complete

Start with Design Tokens

Board reach, low specificity

Sass Variables

$color-brand-blue: hsl(195, 85%, 35%);
$color-brand-orange: hsl(24, 100%, 39%);
$color-brand-pink: hsl(330, 85%, 48%);

👍 DRY

.example {
background: $color-brand-blue;
}
// sass
$brand: (
'blue': hsl(195, 85%, 35%),
'orange': hsl(24, 100%, 39%),
'pink': hsl(330, 85%, 48%),
);
// json
{
'brand': {
'orange': 'hsl(24, 100%, 39%)',
'blue': 'hsl(195, 85%, 35%)',
'pink': 'hsl(330, 85%, 48%)'
}
}
# yaml
brand:
orange: hsl(24, 100%, 39%)
blue: hsl(195, 85%, 35%)
pink: hsl(330, 85%, 48%)

Colors With Adjustment Functions

color.adjust($color, $lightness: 15%)

// json.scss
@include json-encode($colors);
/*! json-encode: '{
'brand-orange': 'hsl(24, 100%, 39%)',
'brand-blue': 'hsl(195, 85%, 35%)',
'brand-pink': 'hsl(330, 85%, 48%)'
}' */
global:
type: "color"
category: "brand-colors"

props:
text_default:
value: "rgb(62, 62, 60)"
text_warning:
value: "rgb(255, 183, 93)"

Relationships Limited To String Interpolation

aliases:
vermilion:
value: "7, 83%"
props:
color_vermilion:
value: "hsla({!vermilion}, 53%, 1)"
color_vermilion_dark:
value: "hsla({!vermilion}, 43%, 1)"
{
"color": {
"theme": {
"brand": { "value": "{color.brand.main.value}" },
"light": { "value": "#ebebeb" }
}
}
}

Global Tokens Color » Text » Action

Category, type, item

Object Tokens Color » Link » Focus

Category, item, state

Know The Trade-Offs Adjust To Your Needs

/// The primary function for
/// accessing colors in your palette...
/// @example scss
/// html {
/// background: color('background');
/// }
/// @param {string | list} $color -
/// The name of a color in your palette...
/// @return {color} -
/// A calculated css-ready color...
@function color(...) {...}

/// @colors
/// @sizes
/// @ratios
/// @fonts

/// These colors are rarely used directly,
/// but form the basis of our palette.
/// @group color
/// @colors
$brand-colors: (
'brand-blue': hsl(195, 52%, 31%),
'brand-orange': hsl(24, 100%, 62%),
'brand-pink': hsl(330, 100%, 45%),
);

Documenting Full Components

Related html, css, and js

<svg data-icon="news" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" width="20px" height="20px" viewBox="0 0 20 20">
<path d="M14.5 14h-6c-0.276 0-0.5-0.224-0.5-0.5v-4c0-0.276 0.224-0.5 0.5-0.5h6c0.276 0 0.5 0.224 0.5 0.5v4c0 0.276-0.224 0.5-0.5 0.5zM9 13h5v-3h-5v3z"></path>
<!-- more paths here -->
</svg>

Herman Supports Nunjucks Examples

Linked from Sass

/// Navigation items, with inactive and active states.
/// @group nav
/// @example njk
/// {% import 'nav.macros.njk' as nav %}
/// {{ nav.bar(active="dashboard", items=[…]) }}
.nav-bar {
/* … */
}
<docs>
```jsx
<nav-bar active="Dashboard" :navItems="[…]"/>
```
</docs>
/* @docs
label: Box Sizing
category: reset
note: |
Use border-box by default, globally.
*/

*, ::before, ::after { box-sizing: border-box; }
{# @docs
label: pullquote
category: typesetting
params:
text:
type: string
note: Rendered as block markdown
#}

{% macro blockquote(text) %}{% endmacro %}
/* @docs
label: elide
category: typesetting
note: |
Elide HTML at a given word count, and append `…` if elided.
params:
html:
type: string
count:
type: Number
default: 50
*/

const elide = (html, count = 50) => { /* … */ }

Meaningful & Structured Code

Readable by Humans & Machines

Inline Documentation

Helps the human factors…

Agile & Integrated Process

Everyone shares a single-source…