Only 64% of teams include UI patterns in their documentation, according to zeroheight’s Design Systems Report 2025. The same report calls patterns the most opinionated pieces of a system, so the gap is a little odd.
Design system documentation is where a team writes down what its components, tokens and patterns are, how each one is built and when to use it. Designers, developers and content writers read the same pages, which stops people from rebuilding parts that already exist.
What Is Design System Documentation, and How Does It Differ From a Style Guide?
A few neighbors get confused with it all the time. A style guide holds visual rules like color, type scale and logo use, with no code and very little behavior. A component library is the reverse: shipped, working code and no guidance on when to use what. Pattern libraries sit between the two and document solved interface problems, such as a sign-in flow or a search result, as one slice of the whole.
Documentation sits on top of all of them and adds the reasoning behind each one, including intent, usage rules, code, accessibility notes and change history. A component library without that layer is still only a library.
A good page tells the reader which component to pick. It also covers configuration and the reasoning behind the behavior.
The difference between a design system and a style guide comes down to scope, and the documentation is where that scope becomes visible to readers.
Designers, developers, content writers and product managers all end up on these pages, usually hunting for different answers.
Handoff documentation for a single project is a different thing. It describes one set of screens, not the system behind them.
What Should Design System Documentation Include?
Most systems end up with pages for foundations, design tokens, components, patterns, content guidelines and getting-started guides.
UK Parliament’s design system guide writes each page with interaction designers, content designers and developers in mind. Knowing the readers settles what each content type has to answer.
| Content type | Main reader | Question it answers |
|---|---|---|
| Foundations | Designers | Which color, type and spacing values are allowed? |
| Design tokens | Designers and developers | What is the named value, and where does it apply? |
| Components | Developers and designers | Which component fits, and how is it configured? |
| Patterns | Product managers and designers | How do components combine to finish a task? |
| Content guidelines | Content writers | How should the interface text read? |
Design system components fill the most pages, so they set the format the rest of the documentation copies.
Patterns need a rule for where they start. One common way to draw the line borrows from Brad Frost’s atomic design, with atoms and molecules documented as components and organisms and templates as patterns. Frost’s method does not prescribe that documentation split, so treat it as a team convention.
Getting-started guides cover installation, the first component in a new project and where to ask for help. They stay short on purpose.
How to Document a Component
A component page works best with a description, anatomy, variants, states, usage rules, a props or API table and a live code example.
Carbon, IBM’s design system, treats this as a requirement. Every component and pattern needs usage, style, code and accessibility guidance on its website (Carbon Design System contribution documentation).
Usage rules should say when to use the component and when not to, with do and don’t examples. Name the alternative for the “don’t” case so the reader has somewhere to go.
Label every part in the anatomy, list every variant and show each state, from default and hover to focus, disabled and error. Carbon’s component checklist requires every state to appear in the design spec.
A props table lists names, types and defaults. It says nothing about when to pick a “small” size over a “medium” one, so add the intent beside each value. Storybook supports this through a description field on each prop.
Storybook Autodocs reads a component’s args and argTypes and generates the props table and live stories from them (Storybook documentation). The table follows the code instead of copying it, and MDX covers the long-form pages around it.
GOV.UK Design System pages add a “how it works” section and a research section to the usual list. The evidence behind a decision stays attached to the guidance.
The usual way this goes wrong is snippets pasted into a page by hand. They drift from the shipped component, and nothing flags the gap.
How to Document Design Tokens
Each token entry records its name, value, semantic purpose and platform outputs, and the reference page is generated from the token source file so the two cannot disagree.
| Token tier | Example | What the entry must say |
|---|---|---|
| Primitive | color.blue.600 | The raw value and the scale it belongs to |
| Semantic | color.text.link | The role, and which primitive it points to |
| Component | button.background.primary | The component and the states it covers |
Intent is the column most teams leave empty. A semantic token such as color.text.link tells the reader where it applies, while a primitive such as color.blue.600 only describes how it looks.
Style Dictionary reads the JSON token files and writes CSS, SCSS, iOS and Android outputs from that single source. Mozilla Foundation keeps its tokens as a JSON file in GitHub, manages them in Figma with the Figma Tokens plugin (now Tokens Studio) and documents them in Figma pages (Mozilla Foundation design documentation).
The Design Tokens Community Group released the first stable version of its format specification, 2025.10, on 28 October 2025, naming Style Dictionary, Tokens Studio and Terrazzo as reference implementations (W3C Design Tokens Community Group).
State the spec version your token files follow on the reference page, so tool authors know what to expect.
When designers own the values, Figma variables can hold them. In that case the entry names the variable collection and mode each token maps to.
A token named after its appearance breaks the moment the brand color changes, and the docs then describe a value that no longer matches its name. Document the role, not the shade.
How to Document Accessibility for Each Component
Each component page should cover the WCAG success criteria it meets, its keyboard behavior, its ARIA roles and states and what a screen reader announces.
WCAG success criteria and contrast
WCAG 2.2 became a W3C Recommendation on 5 October 2023, adding nine success criteria and retiring 4.1.1 Parsing (W3C, 2023).
Name the version and the level on each page. Buttons and icon buttons cite 2.5.8 Target Size (Minimum), and sticky headers or drawers cite 2.4.11 Focus Not Obscured (Minimum), both Level AA.
Record the color contrast ratio of every text and background pairing on the token and component pages.
The wider web shows why that matters. WebAIM’s February 2026 scan found low-contrast text on 83.9% of the top million home pages, up from 79.1% in 2025.
Keyboard behavior
The W3C’s ARIA Authoring Practices Guide publishes a keyboard interaction model for each widget pattern, so a component page can point to the matching one instead of inventing its own. The page still has to spell out a few things.
- Tab order, and where focus lands first
- What Enter and Space do
- How arrow keys behave inside composite widgets such as tabs and menus
- Escape to close, and where focus returns afterward
ARIA roles and screen reader notes
Document the role, the states and the accessible name a component exposes, then write the announcement a screen reader should produce.
Custom ARIA roles carry a risk the W3C states plainly: “No ARIA is better than bad ARIA.” If a native element does the job, say so on the page.
The data backs that up. In WebAIM’s 2026 scan, home pages using ARIA averaged 59.1 detected errors against 42 for pages without it, though WebAIM notes those pages were also more complex.
Documenting a pattern doesn’t prove the implementation works, though. Carbon shows an accessibility testing status on its stable components, based on tests it runs for every release.
How to Start Documenting a Design System From Scratch
Start with the components teams use most and publish a rough version early. Pages can grow as questions come in.
That beats documenting everything before launch, and the steps below follow the same idea.
- Name the readers and the three or four questions each one asks most often.
- Audit what already ships, in code and in Figma, and rank components by how often products use them.
- Fix one page template and reuse it for every component.
- Document the top of the ranked list first. Magic Patterns’ May 2026 guide makes the same call: cover the daily-use components, then expand.
- Publish at a stable URL while the pages are still thin.
- Watch one developer and one designer look for an answer, and fix wherever they stall.
- Give every page an owner and an update trigger, such as any pull request that touches the component.
When components start life in Figma, the library has to exist before the pages do, and a walkthrough on creating a design system in Figma covers that groundwork.
The sources disagree a little on order. The step-by-step guides from UXPin and Netguru treat documentation as a build-out, with scoping first and writing second. Dan Mall’s advice runs the other way: “Don’t document, chronicle.” Record each decision on the page when it is made.
The steps above fit both, as long as the manual is not written before launch. LogRocket’s warning that documentation left to spare time never gets done is why step seven ties updates to the pull request.
A thin page that exists beats a polished one that doesn’t.
Which Tool Should Host the Documentation?
Host the documentation where the source of truth lives. Storybook fits when components are authored in code and zeroheight when Figma leads, while Supernova suits teams that want tokens and pages on one platform.
| Tool | Source of truth | Best fit | Main limit |
|---|---|---|---|
| Storybook | Code | Developer-led teams | Pages written in MDX |
| zeroheight | Figma, plus Storybook | Figma-led teams | Pages live outside the repo |
| Supernova | Figma, plus a token pipeline | Tokens and pages on one platform | Broader than docs alone |
| Docusaurus | Markdown in the repo | Teams that want full control | No Figma link by default |
| Wiki page | Manual entry | Small systems | Updates happen by hand |
The platform with the longest feature list is the wrong default. A tool that does not read from your source of truth starts drifting with the first changed component.
Storybook
Documentation sits next to the code, so a changed component and its page share one pull request. MDX pages embed live stories and props tables, and Figma connects both ways. The Storybook Connect plugin embeds stories in Figma, and the Designs addon embeds Figma files in Storybook (Storybook documentation).
The downsides are practical. Content writers need a repository workflow to edit a page, and publishing needs hosting, either self-managed or through Chromatic, the publishing tool built by the Storybook team.
zeroheight
zeroheight is documentation-first. It imports components and tokens into pages, and it connects Storybook two ways: a native embed, where you add your Storybook URL once in the styleguide settings, or an iframe embed, where you paste a story URL into each block. Separately, it can sync markdown files from a Git repository into pages (zeroheight help center).
Editing does not need a repository, so designers and writers can own their pages. It is a commercial platform, though, so confirm current plans on its pricing page, and the pages follow the code only as closely as the sync allows.
Supernova
Supernova describes itself as a design system platform that connects tokens, components, documentation and code, and that runs token and code automation pipelines. Its comparison page describes zeroheight as a documentation platform focused on authoring.
Both descriptions come from the vendors, so read them as positioning. Test each product against your own files before committing.
The upside is tokens, pages and code outputs in one place, with Figma, Storybook, GitHub, GitLab, Bitbucket and Azure DevOps connections listed by Supernova. The downside is more platform than a team that only needs pages.
Docusaurus, Figma pages and wikis
- Docusaurus keeps Markdown in the repo and builds it into a static site with versioned docs. It fits when developers own everything, and nothing links it to Figma out of the box.
- A Figma page puts the notes inside the library file. That works for a small system, but code details have nowhere to live.
- Confluence and Notion wikis make sense when the company already runs one, and Atlassian ships a design component template for Confluence. Updates happen by hand unless someone wires them up.
Who Owns and Maintains the Documentation?
Somebody has to own it, and the team model decides how fast pages change. Nathan Curtis’s terms are still the usual way to describe it.
Ownership and contribution process
In Curtis’s terms, a solitary team publishes the system for its own needs and lets others borrow it. A centralized team produces and supports it for everyone else, while in a federated setup designers from several product teams decide on the system together. Curtis published the models in 2015, and teams still use them as the common vocabulary.
Salesforce’s Lightning Design System ran a mix. A very small centralized team acted as librarian and distributor, while federated contributors from product teams kept the system accurate and current (Jina Bolton, 2015).
Write the contribution flow on the site itself, where a contributor looks first: request, draft on the page template, review by a core member, merge, changelog entry.
Tracking adoption
Only 38% of design systems reach wide adoption, according to zeroheight’s Design Systems Report 2026 (147 respondents).
Component usage per component is the obvious number to watch. Documentation coverage, meaning the share of components with a finished page, is easy to count. Support request volume per component, compared before and after its page ships, takes more effort and tells you more.
Figma’s Library Analytics API reports insertions and detachments per component and usage by component, style or variable, recalculated daily at 00:00 UTC. As of October 2026, the API is limited to Enterprise plans, while the in-app library analytics (Design System Analytics) are available on Organization and Enterprise plans (Figma documentation).
Bukalapak used to measure adoption late, by analyzing component usage in its iOS and Android codebases. Design System Analytics let the team see library and component adoption during the design phase instead (Figma).
A detachment is a signal, not a verdict. Figma itself advises weighing the original intent of a component before reading the numbers.
How to Version Changes and Keep Documentation in Sync With Code
Version the system with Semantic Versioning and log every change in a changelog. Removals go through deprecation notices, and as much of the reference as possible should be generated from code and Figma.
Changelogs and semantic versioning
Under Semantic Versioning 2.0.0, a major release covers incompatible API changes. Minor releases add backward-compatible functionality and also cover any public API marked as deprecated, and patch releases are for backward-compatible bug fixes.
The spec requires a declared public API, so declare one. For a design system that means component props and token names.
A renamed token or a removed prop is a major release. A color adjustment is a call your team makes once and writes down.
Each changelog entry says what changed and why, and breaking changes get a migration path. Docusaurus freezes docs per release: the docs:version command copies the docs folder into versioned_docs and adds a version dropdown (Docusaurus documentation).
Deprecation notices
Atlassian Design System runs three release phases and two deprecation phases, and states that no General Availability feature is removed without a clearly announced deprecation period.
In the first deprecation phase, Intent to Deprecate, the feature is under review and new work should use the recommended alternative. Once it is Deprecated, it is unsupported and will be removed after the deprecation period, with a replacement named.
When Atlassian deprecated exports in its logo package, the notice shipped with a codemod that rewrites imports automatically. The component page should carry the same facts: status, replacement and removal date.
Syncing documentation with Figma and code
Code Connect links Figma components to their code. Once linked, Dev Mode shows true-to-production snippets from the design system instead of autogenerated ones.
Per the project’s README, Code Connect is available on Organization and Enterprise plans and needs a full Design or Dev Mode seat.
A few habits keep the pages honest.
- Run the documentation build in CI, so a broken story fails the pull request
- Add “documentation updated” to each component’s definition of done
- Link every page to its source file and its Figma component
Sync only moves what was connected, though. A prop added in code but missing from the story never reaches the page.
Why Design System Documentation Fails, and When a Full Documentation Site Is Too Much
Documentation usually fails for organizational reasons rather than technical ones, mostly because nobody owns it and nobody budgets time for it.
- Okoone’s guide says most organizations fail by writing for themselves, not for the people using the system.
- LogRocket ties stale pages and weak adoption to documentation that is not prioritized alongside component delivery.
- A page without a named owner has nobody to correct it.
- A big first release delays the feedback that shows which pages matter.
- Some teams buy the platform before anyone has decided whether Figma or code wins.
A full documentation site makes sense when several product teams consume the system and a named owner has time to run it. It also helps when designers, developers and writers all edit pages.
A README, Storybook Autodocs or a single Figma page is enough when one product team builds and uses the components. Same goes for a system small enough for one person to hold in their head, or a team with no time to run a platform.
Storybook Autodocs already gives developers a props table and live stories without a second platform.
Vendors price and repackage plans often, so confirm current figures on each pricing page before budgeting. Move to a platform when a second consuming team shows up, not before.
Design System Documentation FAQ
How long does it take to document a design system?
It depends on the number of components and the people writing, so a single figure would mislead.
Publish the most-used components first and add pages as questions come in.
Where can I find a design system documentation template?
Carbon, UK Parliament’s design system and Atlassian all publish one. Carbon offers markdown templates for usage, style, code and accessibility pages, Parliament’s guide includes a template for new components, and Atlassian provides a component template in Confluence.
Should the content style guide sit inside the documentation or beside it?
Either placement works. Keep it inside when the guidance is short, and separate when voice and microcopy rules run long, a split UXPin’s codification guide also recommends.
In both cases, link each component page to the rules that apply.
Can AI coding agents read design system documentation?
Yes, and the structure of the pages decides how well. Storybook’s AI guidance says agents depend on how well a system documents each component’s purpose, usage and API, and that the same effort helps human developers.
Text-based props, stated intent and explicit do and don’t rules give an agent something to act on. Screenshots give it nothing to parse.
The Smallest Set of Pages Worth Shipping First
A small team should start with a getting-started page, then the most-used component pages, and add a token reference after that.
The order follows expected question volume. Component pages draw the most daily questions, and a token reference generated from the source file costs almost nothing to keep current.
The trade-off is a gap. With patterns and content guidelines deferred, product teams assemble components their own way until those pages land.
As of 26 October 2026, this order holds until the first breaking change ships. Then a changelog and versioning move to the front, and broader design system best practices decide what to tighten next.
- How to Flip an Image in Figma Quickly? - November 18, 2026
- How to Comment in Figma Like a Pro - November 16, 2026
- How to Make a Pie Chart in Figma Without Plugins - November 14, 2026


