Design System Documentation Template

What This Template Is For

A design system without documentation is a Figma file that three people understand and nobody else trusts. Documentation is what turns a collection of components into a system that scales across teams. Good documentation answers four questions for every component: what it looks like (specs), when to use it (guidelines), how it behaves (states and interactions), and how to implement it (code).

This template provides a repeatable format for documenting each component in your design system. It covers visual specs (sizing, spacing, color tokens), usage guidelines (when to use and when not to use), variants and states, accessibility requirements, and code implementation notes. The same format works for atoms (buttons, inputs), molecules (search bars, cards), and organisms (navigation bars, data tables).

This pairs with the accessibility audit template for ensuring each component meets WCAG 2.1 AA standards and the design handoff template for communicating component usage to engineers. Teams evaluating their design system maturity can use the AI Design Maturity Model to benchmark where they stand. For broader design process documentation, the design review template provides a framework for reviewing new component proposals.

How to Use This Template

1. Document one component at a time. Start with the most-used components (buttons, inputs, cards, modals) since those have the highest impact on consistency.
2. Fill in the Component Overview first: name, description, status, and Figma link. This orients anyone discovering the component for the first time.
3. Write the Usage Guidelines before the visual specs. Knowing when to use a component is more important than knowing its exact padding values.
4. Document all variants and states, including edge cases (loading, error, disabled, empty, overflow). Missing states cause engineers to invent their own, breaking consistency.
5. Include accessibility requirements as a core section, not an afterthought. Each component should specify keyboard behavior, ARIA attributes, contrast requirements, and screen reader announcements.
6. Add code examples that show real usage, not abstract examples. Copy-pasteable code reduces implementation errors.

The Template

Component Overview

Description. [1-2 sentences. What does this component do? What problem does it solve?]

Usage Guidelines

When to use:

• ☐ [Scenario where this component is the right choice]
• ☐ [Another appropriate scenario]
• ☐ [Context where this component solves a specific problem]

When NOT to use:

• ☐ [Scenario where a different component is better. Name the alternative.]
• ☐ [Anti-pattern or misuse that teams commonly attempt]
• ☐ [Edge case where this component breaks down]

Placement guidelines:

• [Where this component appears in the layout: page header, card footer, modal bottom, etc.]
• [How it relates to adjacent components: spacing from other elements, alignment]
• [Maximum count per view: e.g., "One primary button per view"]

Variants

States

Design Tokens

Sizing

Accessibility Requirements

• ☐ Keyboard: [Describe keyboard behavior, e.g., "Activates on Enter and Space. Tab to focus."]
• ☐ Screen reader: [Describe announcements, e.g., "Announces label + role ('Submit, button')"]
• ☐ ARIA: [Required ARIA attributes, e.g., "aria-disabled='true' when disabled, not disabled attribute on non-button elements"]
• ☐ Contrast: [Minimum contrast ratios, e.g., "Text on primary: 4.6:1 (passes AA). Focus ring: 3:1."]
• ☐ Touch target: [Minimum size, e.g., "44x44px minimum for mobile (WCAG 2.5.8)"]
• ☐ Motion: [Animations respect prefers-reduced-motion, e.g., "Loading spinner pauses when reduced motion is set"]

Content Guidelines

Code Examples

// Basic usage
<Button variant="primary" size="md" onClick={handleSubmit}>
  Save Changes
</Button>

// With loading state
<Button variant="primary" loading>
  Saving...
</Button>

// Destructive with confirmation
<Button variant="destructive" onClick={handleDelete}>
  Delete Project
</Button>

// Icon + label
<Button variant="secondary" icon={<PlusIcon />}>
  Add Item
</Button>

Props API:

Related Components

Filled Example: Button Component

Component Overview

Description. Buttons trigger actions. They are the primary interactive element for user-initiated operations (submit, save, delete, navigate, toggle).

Usage Guidelines

When to use: Form submission, dialogs (confirm/cancel), page actions (create, export), navigation to a different context.

When NOT to use: Navigation within the same page (use a link instead). Toggling between states (use a toggle switch). Selecting from multiple options (use radio buttons or a select). If it navigates to a URL, use an tag styled as a button, not a .

Placement: One primary button per visible viewport. Place the primary action on the right in button groups. Destructive buttons go on the far left, separated by a spacer.

Accessibility

• ☑ Keyboard: Activates on Enter and Space. Focus ring visible on Tab.
• ☑ Screen reader: Announces label + role ("Save Changes, button"). Loading state adds aria-busy="true".
• ☑ Contrast: Primary text on background: 5.2:1. Destructive text on background: 4.8:1. Both pass AA.
• ☑ Touch target: 44x44px minimum on mobile (padding extends hit area even when visual size is smaller).
• ☑ Disabled state uses aria-disabled="true" and explains why via aria-describedby pointing to helper text.

Key Takeaways

• Document usage guidelines before visual specs. Knowing when to use a component matters more than its padding values
• Cover all states, including edge cases (loading, error, disabled, overflow, empty)
• Embed accessibility requirements as a core section, not a separate audit
• Include copy-pasteable code examples that show real usage patterns
• Assign a component owner responsible for keeping the documentation current

---

About This Template

Created by: Tim Adair

Last Updated: 3/4/2026

Version: 1.0.0

License: Free for personal and commercial use