Integrated Documentation

@ Smashing Online

So We Built Some Beautiful Systems

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

If We Don’t Know The Patterns

If We Don’t Use The Patterns

There Won’t Be Any Patterns

Solve A Human Problem

Solve A Process Problem

Simplify Design Decisions

Simplify Code Decisions

Simplify Team Communication

Simplify Best Practice

Single Source of Truth

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

Salesforce Lightning Design System
Lonely Planet Design System
Mailchimp Grids
Size Previews
Mailchimp Voice
Salesforce LDS Motion System
New York City Transit Authority Graphic Standards Manual
Numbers 5-8
Diagram of sign construction

Design Systems Represent Integration

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

Design Systems

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

Involve The Full Team

Represent Multiple Concerns

Lego Component Library
Lego Organizer
Lego Airplane
Girl from an 80s Lego commercial,
holding her fantastic creation with a smirk
Baby eating a Lego block
LDS icons with markup
Scribbled out LDS icons with markup

You are not MailForce or InstaFace

(unless you are)

Similar Problems Unique Constraints

(Team Size)

(Team Structure)

(Internal vs. Consulting)

(Private vs. Public)

(Is it 1970?)

OddBird Consulting

Custom Apps, Design Systems, Training, & Refactors

How do you sell it To Clients or Bosses?

YMMV (We Often Don’t)

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

Lower Maintenance Costs

Lower Maintenance Time

Better Team Communication

Faster Feature Development

Consistent Design Patterns

More Time for Details

Encourage Best Practice

Encourage Accessibility

Accessibility Is A Basic Human Right


(Learn To Test)

Accessibility is For Everyone

Along any number of spectrums

Provide Accessible Patterns

Document Accessible Use Cases

Along with uses to avoid

What Do We Have Already?

Take Screenshots & Organize

Design patterns from the Hillary campaign, 
printed on paper, cut apart,
and labeled with sticky notes
printed and cut-out UI elements grouped on a page

What Do We Need?

What’s The Code Stack?

What’s The Process?

Start Small Get It Right & Expand

Continuous Integration Accurate > Complete

Continuous Integration Maintained > Complete

Avoid Separate Forks

Start Designing Look for Patterns

Go Back Iterative Process

Start With What You Know

Start With What Has Most Reach

Start with Design Tokens

Board reach, low specificity

A color palette with 3 colors and their code values

Sass Variables

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


.example {
background: $color-brand-blue;

👎 Not Organized

👎 Encourages One-Offs

👎 Difficult to Automate

Make Systems The Lazy Option

Automate From Structured Code

// 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
orange: hsl(24, 100%, 39%)
blue: hsl(195, 85%, 35%)
pink: hsl(330, 85%, 48%)

Sass Provides Design Data Types

Lengths With Unit-Math

16px + 12cm

Colors With Adjustment Functions

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

Pick One Source And Export Anywhere

// 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%)'
}' */

Salesforce YAML + Theo

type: "color"
category: "brand-colors"

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

Relationships Limited To String Interpolation

value: "7, 83%"
value: "hsla({!vermilion}, 53%, 1)"
value: "hsla({!vermilion}, 43%, 1)"

Advantage? More Generic Syntax

Amazon Json + Style Dictionary

Relationships Limited To Name Alias

"color": {
"theme": {
"brand": { "value": "{color.brand.main.value}" },
"light": { "value": "#ebebeb" }
A hierarchy of category (color),
type (background),
item (button),
sub-item (primary),
and state (active)

Let Data Determine Structure?

Global Tokens Color » Text » Action

Category, type, item

Object Tokens Color » Link » Focus

Category, item, state

Know The Trade-Offs Adjust To Your Needs

Integrated Documentation Generators

/// 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(...) {...}
Generated site, showing mixins and functions

/// @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%),
Herman Color Previews
Herman Scale Previews (Rulers)
Herman Ratio Previews
Herman Font Specimens

Documenting Full Components

Related html, css, and js

Components Also Provide Meaning

<svg data-icon="news" xmlns="" 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 -->

<icon name="gear" />

Built-In Consistency & Accessibility

Built-InAPI” for Modifiers

Document… Proper Usage

Document… Allowed Modifications

Where Do We Document?

What Can We Automate?

Depends on Stack or Framework

Depends on Who Maintains It

Herman is Sass-Driven

Herman Supports Nunjucks Examples

Linked from Sass

/// Navigation items, with inactive and active states.
/// @group nav
/// @example njk
/// {% import 'nav.macros.njk' as nav %}
/// {{"dashboard", items=[…]) }}
.nav-bar {
/* … */
Rendered nav component

Framework-Specific Tools

Vue Design Systems
<nav-bar active="Dashboard" :navItems="[…]"/>
Rendered VueDS Component
Screenshot of storybook showing a button component

Build Your Own With Doxray + (Eleventy?)

Parses Comments as YAML

/* @docs
label: Box Sizing
category: reset
note: |
Use border-box by default, globally.

*, ::before, ::after { box-sizing: border-box; }

Define Your Own Annotations

Customize For Any Language

{# @docs
label: pullquote
category: typesetting
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.
type: string
type: Number
default: 50

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

Render Docs However You Like

Meaningful & Structured Code

Readable by Humans & Machines

Inline Documentation

Helps the human factors…

Agile & Integrated Process

Everyone shares a single-source…