Integrated Documentation

Miriam Suzanne @ Smashing Online

May 22, 2020

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

New York City Transit Authority Graphic Standards Manual

Design Systems Represent Integration

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

Design Systems

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

Involve The Full Team

Represent Multiple Concerns

Girl from an 80s Lego commercial,
holding her fantastic creation with a smirk

You are not MailForce or InstaFace

(unless you are)

(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

Perceivable,
Operable,
Understandable,
Robust

(Learn To Test)

Browser DevTools
Axe DevTools
VoiceOver (Mac)
NVDA (PC)

Accessibility is For Everyone

Along any number of spectrums

Provide Accessible Patterns

Document Accessible Use Cases

Along with uses to avoid

Audit Existing Materials
Plan Your Approach
Structured Code
Integrate Tools & Process

What Do We Have Already?

Take Screenshots & Organize

Design patterns from the Hillary campaign,
printed on paper, cut apart,
and labeled with sticky notes

cssstats.com

printed and cut-out UI elements grouped on a page

Audit Existing Materials
Plan Your Approach
Structured Code
Integrate Tools & Process

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

Audit Existing Materials
Plan Your Approach
Structured Code
Integrate Tools & Process

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%);

👍 DRY

.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
brand:
  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

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)"

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

Audit Existing Materials
Plan Your Approach
Structured Code
Integrate Tools & Process

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%),
);

Documenting Full Components

Related html, css, and js

Components Also Provide Meaning

<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>

`<``icon` `name="gear" />`

Built-In Consistency & Accessibility

Built-In “API” 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 %}
///   {{ nav.bar(active="dashboard", items=[…]) }}
.nav-bar {
  /* … */
}

Framework-Specific Tools

<docs>
  ```jsx
  <nav-bar active="Dashboard" :navItems="[…]"/>
  ```
</docs>

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
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) => { /* … */ }

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…