qa-aman/design-system-doc

Overview

Based on "Atomic Design" by Brad Frost. A design system is not a component library - it's a shared language. Frost's insight: components without documentation are just code. Documentation is what transforms a component library into a system that a whole team can use consistently without needing to ask the original designer.

Design system documentation has two audiences: designers who need to use the pattern correctly, and engineers who need to implement it accurately. Write for both.

Workflow

Step 1: Establish the entry structure

Every design system entry should follow the same structure so team members can predict where to find information:

1. Overview (what this is, one paragraph)
2. When to use / when not to use
3. Anatomy (labeled diagram of all parts)
4. Variants
5. States
6. Design tokens used
7. Usage examples (correct and incorrect)
8. Accessibility
9. Related components
10. Changelog

Step 2: Write the overview

One paragraph: what is this component/pattern? What job does it do in the UI?

Include a simple visual (or Figma embed) showing the component in its default state.

Step 3: When to use / when not to use

This is the most important section. Design systems fail when components are used outside their intended context.

Use when:
- [specific context 1]
- [specific context 2]

Don't use when:
- [anti-context 1] - use [alternative] instead
- [anti-context 2] - use [alternative] instead

Step 4: Document the anatomy

Label every part of the component. Each part should have:

• A name (used consistently in code and design)
• Whether it's required or optional
• Constraints (max length, image dimensions, etc.)

Step 5: Document design tokens

List every token the component uses:

| Token | Value | Role | |-------|-------|------| | color.interactive.primary | #0066CC | Background color | | spacing.md | 16px | Internal padding | | radius.sm | 4px | Border radius | | typography.body.md | 16px / 24px | Label text |

Using tokens (not hardcoded values) ensures the component responds correctly to theme changes in [your design system].

Step 6: Add usage examples

Show correct and incorrect usage with visual examples:

Correct: [example with explanation of why it's correct] Incorrect: [example with explanation of why it's wrong and what to do instead]

At least 2-3 of each. Real examples beat abstract rules.

Step 7: Document accessibility

• Keyboard interactions
• Screen reader behavior
• Required ARIA attributes
• Color contrast compliance (WCAG AA)
• Touch target size compliance

Step 8: Add a changelog

Every time the component changes, log it:

v1.2 - [date] - Added loading state. [your team]
v1.1 - [date] - Updated border radius to match new tokens. [your team]
v1.0 - [date] - Initial release. [your team]

Anti-Patterns

1. Documentation written only for designers Bad: Docs describe visual design but no tokens, props, or accessibility. Good: Document at both design and implementation level. Engineers should be able to build from the doc alone.

2. No "when not to use" section Bad: Only positive usage guidance. Good: "When not to use" prevents misuse and is often more valuable than "when to use."

3. Hardcoded values instead of tokens Bad: Component documented with hex codes and pixel values. Good: Everything references a named token. Tokens are the vocabulary of [your design system].

4. No changelog Bad: Component updated silently. Good: Every change logged with version, date, and author. [Your team] can see what changed and when.

Quality Checklist

• [ ] Standard entry structure followed (overview through changelog)
• [ ] When to use AND when not to use documented
• [ ] Anatomy labeled with names used in both design and code
• [ ] All design tokens documented (not hardcoded values)
• [ ] Correct and incorrect usage examples included
• [ ] Accessibility: keyboard, screen reader, ARIA, contrast
• [ ] Changelog entry added for this version
• [ ] Related components cross-referenced