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
Design Systems
Represent Integration
Design & Code & Process & Tools & Docs & ???
Design Systems
Style Guides + Tool Kits + Component Libraries + ???
Involve
The Full Team
Represent
Multiple Concerns
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
Perceivable ,
Operable ,
Understandable ,
Robust
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
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
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
$brand : ( 'blue' : hsl ( 195, 85%, 35%) , 'orange' : hsl ( 24, 100%, 39%) , 'pink' : hsl ( 330, 85%, 48%) , ) ;
{ 'brand': { 'orange': 'hsl(24 , 100 %, 39 %)', 'blue': 'hsl(195 , 85 %, 35 %)', 'pink': 'hsl(330 , 85 %, 48 %)' } }
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
@include json-encode ( $colors ) ;
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" } } } }
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
@function color ( ...) { ...}
///
@colors
///
@sizes
///
@ratios
///
@fonts
$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> </ 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
Framework -Specific Tools
< docs> ```jsx < nav-bar active = " Dashboard" :navItems = " […]" /> ```</ docs>
Build Your Own
With Doxray + (Eleventy ?)
Parses
Comments as YAML
*, ::before, ::after { box-sizing : border-box; }
Define
Your Own Annotations
Customize
For Any Language
{% macro blockquote ( text ) %} … {% endmacro %}
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…
@MiriSuzanne
Miriam Suzanne