How to Document a Design System: Best Practices and Tools

Good design system documentation helps people make the right design and implementation decisions while they work. It explains the system’s purpose, when to use a component or pattern, how it behaves, and how to contribute when the system does not yet cover a need.

Build documentation in layers: principles and foundations, components, patterns, implementation guidance, and operations. Choose a home that fits your audiences and maintenance capacity, connect design intent to code examples, and make updates part of the system’s regular lifecycle.

1. Start with purpose and principles

Before listing tokens or components, explain what the system is for and who it serves. A designer choosing a pattern, an engineer implementing it, and a content designer reviewing its language may need different views of the same system.

Write down the principles that guide decisions when a rule is not explicit. Keep them practical: describe the intended outcome and how a team can apply it. Figma’s guidance describes documentation as the part that communicates the purpose of a system and how to apply it (Figma: Document and manage your system).

Include a short orientation page with:

What the system covers, and which products or platforms use it.
Who the main audiences are and where each audience should start.
The system’s principles and the decisions they help resolve.
How to find a component, request a change, or report a gap.
Who owns the system and how its documentation is maintained.

2. Document foundations before components

Foundations make component decisions consistent. Document the design values that teams share, including color, typography, spacing, layout, motion, elevation, iconography, and naming conventions where they apply.

For each foundation, state its purpose, available values, intended use, and any constraints. If the source of truth is a token package or design file, link to it and explain how its names map to the rendered interface.

Foundation	Useful documentation
Color	Semantic roles, examples, contrast guidance, and status cues that do not depend on color alone.
Typography	Type roles, hierarchy, responsive behavior, and examples of long or constrained content.
Spacing and layout	Scale, grid or alignment rules, breakpoints, and examples of common arrangements.
Tokens	Names, values or references, intended meaning, and the relationship between design and code names.
Motion and elevation	Where effects are appropriate, their purpose, and any reduced-motion or layering considerations.

Prefer names that communicate purpose when consumers need to choose by meaning. For example, a semantic color role such as “danger” can communicate intent more clearly than a raw color name or hexadecimal value. Keep the underlying values available for implementation, but do not make consumers infer meaning from them.

3. What to include in component documentation

A useful component page lets a reader decide whether the component fits, understand its behavior, and implement or configure it without guessing. Write for someone who has never seen it before, define necessary specialist terms, and use examples to clarify choices.

Component page checklist

Purpose: what the component does and the user need it supports.
Use it when: the situations where it is a good fit.
Do not use it when: nearby alternatives or cases it does not handle well.
Anatomy: the component’s meaningful parts and their names.
Variants and states: available options, default behavior, and states such as hover, focus, disabled, loading, error, or selected when relevant.
Behavior: what happens on interaction, how state changes, and how it adapts to content and viewport changes.
Examples: representative uses, edge cases, and examples of incorrect or discouraged use where those prevent confusion.
Accessibility: keyboard operation, focus behavior, accessible name or description, assistive technology behavior, contrast or non-color cues, and testing expectations.
Implementation: code examples, API or prop references, framework notes, and a link to a live example if available.
Design reference: a link to the design source or annotations, with enough context to relate it to the implementation.

Keep the page proportionate. A simple icon button may need a compact page; a dialog or multi-step control may need detailed interaction examples and accessibility guidance. Make the important decision visible before the full API reference.

Show choices, not just available options

A list of variants says what exists; usage guidance helps a reader choose. Explain what each variant is for, whether variants can be combined, what happens at narrow widths, and what to use when the content does not fit. Where a component should not be adapted for a particular task, explain the supported alternative.

4. Document patterns and layouts

Patterns describe how components work together to support a common user goal. They answer questions that single-component pages cannot, such as how a form should handle validation or how a navigation flow should adapt to smaller screens.

For each pattern, include its intended goal, the recommended sequence or composition, interaction and responsive behavior, content considerations, accessibility requirements, and links to the components it uses. Include a representative example that shows the whole flow, not just a collection of isolated parts.

CMS organizes its public design system into guidelines, foundations, components, patterns, layouts, and utilities. Its designer guidance recommends starting with existing components and documenting gaps or deviations when the system cannot meet a need (CMS Design System: For designers).

5. Connect design intent to implementation

Designers and developers often consult different tools. Keep their guidance connected even when it cannot live in one place. Design-file annotations and component descriptions can explain intent; code examples and interactive stories can explain implementation and behavior. Link between them from the relevant component or pattern page.

Storybook supports prose, layout, automatically generated Autodocs pages, and custom MDX pages. Its documentation guidance notes that stories written during development can become basic documentation to revisit later (Storybook: How to document components).

For code-facing documentation, keep examples close to the component and aligned with its supported API. Show realistic values and the relevant states. If the design and code sources use different names, explain the mapping. Avoid copying a code reference into a second location if it will drift; link to the maintained source instead.

6. Choose where documentation should live

There is no universal best home. Choose based on the people who need the information, how they find it, the type of content, integration with existing work, and who will maintain it. A dedicated site can support multiple audiences and specialized pathways, but it adds setup and upkeep. A small team may move faster with clear ownership in shared workspaces and design files.

Home	Works well for	Consider
Figma or design files	Design foundations, annotations, component descriptions, and links used during design work.	Readers outside the design workflow may need a direct route to implementation guidance. Link out when information lives elsewhere.
Storybook	Coded components, executable stories, and documentation maintained beside implementation.	Decide how design intent, broader principles, and non-code audiences will find their guidance.
Dedicated documentation site	Multiple products or audiences, customized navigation, and longer-form guidance.	Budget for building, ownership, content review, and ongoing maintenance.
Shared team workspace	A quick start for a smaller team using existing tools.	Use clear navigation, ownership, and links so content remains findable as it grows.

This is a practical comparison of capabilities and tradeoffs, not a ranking. Teams can combine homes, provided each page has a clear source of truth and links to related design and code guidance. Figma’s documentation lesson discusses both design-file and dedicated-site approaches and recommends making external documentation easy to reach from the component (Figma Help Center).

7. Make accessibility and plain language explicit

Accessibility belongs in the usage instructions, not only in a separate policy. Explain the interaction requirements and behavior that apply to each component and pattern. Depending on the element, this can include keyboard input, focus order and visibility, accessible names, announcements, contrast, non-color cues, and reduced motion.

State how the guidance was checked and what consumers should verify in their own context. Ask people with different accessibility needs to review the system and its documentation. Figma’s system guidance cautions against using color alone to communicate status and calls for testing with a range of users (Figma: Define your design system).

Use plain language and define specialist terms when they are needed. Prefer functional names over names based only on appearance where that helps consumers select the right option. Avoid stating legal compliance requirements without checking the applicable standard and jurisdiction for the product.

8. Build documentation into governance and maintenance

Documentation becomes stale when updates depend on someone remembering to revisit it later. Treat it as part of a component or pattern’s definition of done, and record decisions while the context is still clear.

Assign ownership. Name a team or role responsible for each major area and a route for questions.
Define contributions. Explain how to propose a component, report a gap, or change existing guidance.
Set review expectations. Identify who approves changes that affect design, code, content, or accessibility.
Update alongside the system. Include documentation in component and pattern changes, including examples and links.
Collect feedback. Give consumers a visible way to report unclear or missing guidance.
Support onboarding. Provide a starting path and training information for new contributors and consumers.

Figma’s governance guidance raises the practical questions teams need to answer: how updates happen, how feedback is gathered, who approves changes, and how people collaborate and learn the system (Figma Help Center).

9. A practical rollout sequence

Identify audiences and tasks. List the decisions designers, developers, and other consumers need to make.
Inventory the current system. Find existing foundations, components, patterns, design references, and code examples.
Set the information structure. Use the five layers: principles and foundations, components, patterns, implementation, and operations.
Choose the documentation home. Start where consumers already work, then link sources together.
Document a representative component. Use the checklist above and ask likely consumers to try the page without extra explanation.
Use feedback to refine the template. Fix missing decisions and confusing terms before documenting the full catalog.
Assign owners and update rules. Add documentation updates to the normal change process.

10. Common documentation problems and fixes

Problem	Why it happens	Fix
Pages list variants but do not explain which to choose.	The content describes inventory rather than decisions.	Add “use it when,” “do not use it when,” and concrete examples for each meaningful choice.
Design and code guidance disagree.	References live separately and changes do not update both.	Name the source of truth, link between the sources, and include both in the change review.
People cannot find the page.	Documentation is detached from the tools or components people use.	Link from design files, component descriptions, code stories, and the team’s normal starting point.
Guidance becomes stale.	Ownership and update responsibilities are unclear.	Assign owners and make doc changes part of component and pattern completion.
Examples do not cover real content.	Only ideal or minimal states were documented.	Add representative edge cases, such as long labels, empty states, validation, or narrow layouts where relevant.
Accessibility is mentioned only in general terms.	Requirements are not tied to component behavior.	Document keyboard, focus, assistive technology, contrast, and testing details that apply to that component or pattern.

11. Use screenshots to make visual guidance concrete

Screenshots can help show a component in context, compare states, or illustrate a multi-step pattern. Keep the explanation in text as well, so the documentation remains useful when an image is unavailable and can be understood by assistive technology. Capture examples from stable routes and representative content, and update them when the documented behavior changes.

For a browser-based documentation page, a screenshot API can provide repeatable captures for visual examples. ScreenshotNeo is a website screenshot API and MCP server for developers, made by Yorker Media. A GET request with a URL can return a PNG, JPEG, WebP, or PDF. Its documented options include full-page or selector captures, custom CSS, viewport and device settings, and waiting for a selector, delay, or network idle. See the ScreenshotNeo documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Keep API keys on a server or in a protected environment variable; do not put a secret key in a public documentation page or browser-side example. Check the response and save the returned image bytes. The JavaScript example uses Bun’s file writer; in Node.js, use node:fs/promises to write the response bytes.

Or skip the browser setup

ScreenshotNeo’s one-call request captures a URL. Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the API documentation and ScreenshotNeo. Sign up for 1,000 free screenshots a month with no card.

12. Keep capture reliable, fast, and within budget

For repeatable visual references, use stable pages and consistent viewport settings, wait for the content that matters, and avoid capturing on every documentation page view if a saved example is sufficient. Cache captures when appropriate, refresh them when the documented page changes, and use async jobs or bulk capture for larger sets. ScreenshotNeo supports configurable caching, asynchronous jobs with signed webhooks, and bulk capture of up to 100 URLs per call; see its docs for request options.

Image capture has operational costs: pages can load slowly, third-party resources can fail, and dynamic content can make examples inconsistent. Use a timeout appropriate to the page, choose a deliberate wait condition, and keep a known-good text explanation alongside the image. ScreenshotNeo states that only clean shots are billed; bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, with the page verdict and billing status reported in response headers.

ScreenshotNeo plans are Free: 1,000 shots a month; Starter: $5 for 3,000; Growth: $15 for 15,000; Pro: $39 for 60,000; Scale: $99 for 250,000; Business: $249 for 1,000,000. Yearly billing gives two months free, and every feature is on every plan. Select a plan based on capture volume and refresh frequency; avoid generating duplicate captures when a cached image remains accurate.

13. Frequently asked questions

Where should design system documentation live?

Put it where its main readers can find it during their work. Design files, Storybook, a dedicated site, or a shared workspace can all work; connect the sources when design and implementation guidance live separately.

What should I document first?

Start with purpose, principles, foundations, and one representative component. That establishes the structure and reveals what consumers need before the whole catalog is written.

How detailed should a component page be?

Detailed enough that a new consumer can choose, use, and implement it safely. The complexity of the behavior and accessibility needs should determine the page length.

Who should maintain the documentation?

Assign owners for system areas and require the relevant documentation to change alongside components and patterns. Invite the people who use the system to report gaps and unclear guidance.