How to Document Design Systems in Storybook

Document a design system in Storybook by treating it as a living reference: write stories for meaningful component states, use Autodocs to generate a consistent starting page, and add MDX for usage guidance, design rules, and explanations that cannot be inferred from component code. Then review the rendered docs and build them with the project.

Stories show what a component looks like in specific states. Autodocs turns story metadata and examples into repeatable component documentation. MDX lets you add the reasoning and broader guidance that stories alone cannot convey. You can use all three together.

1. Model component states as stories

A story is a rendered state of a UI component. Give stories names that describe meaningful variations or conditions, rather than documenting only the default. For a button, that could include its primary and secondary variants, disabled state, and a long-label case. For a form field, it might include default, invalid, and disabled states.

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  args: {
    children: 'Save changes',
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    variant: 'primary',
  },
};

export const Secondary: Story = {
  args: {
    variant: 'secondary',
  },
};

export const Disabled: Story = {
  args: {
    disabled: true,
  },
};

export const LongLabel: Story = {
  args: {
    children: 'Save changes and return to the project overview',
  },
};

This is a TypeScript CSF example for a React component. Adapt the component and framework imports to your project. The story names and args are examples: use the props your component actually supports. TypeScript CSF can provide type safety and autocomplete in the MDX workflow as well.

Choose representative states

• Include the variants that users of the system are expected to choose between.
• Show important behavioral states, such as disabled or invalid, where the component supports them.
• Include edge cases that affect layout or understanding, such as unusually long content.
• Keep stories purposeful. A catalog of nearly identical examples makes it harder to find the meaningful differences.

2. Enable Autodocs for a consistent baseline

Autodocs generates documentation pages from story files and their metadata. Tag a component’s stories with autodocs, as in the example above. If you want this behavior broadly, enable the tag globally in your preview configuration instead; check the documentation for your installed Storybook version for the exact configuration location and syntax.

Autodocs can infer information such as args, argTypes, and parameters, and present stories and API information consistently. It is a starting point generated from what your code and stories describe. It cannot infer your design rationale, when a variant is appropriate, or how a component relates to the rest of the system.

When to use Autodocs

• Use it for repeatable component pages driven by metadata and examples.
• Use it to make the available component states and API easier to browse.
• Use it as the baseline when many components need a consistent documentation shape.

3. Add authored guidance with MDX

Use MDX when authors need to explain intent or provide a page structure beyond the generated reference. It can combine Markdown prose, CSF stories, Doc Blocks, and JSX. That makes it suitable for usage patterns, design principles, accessibility guidance, token explanations, onboarding, and guidance spanning multiple components.

An MDX page can attach to a stories file through the of prop on Meta. That creates a docs entry associated with those stories. Here is a compact example:

import { Meta, Canvas, Controls } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# Button

Use the primary button for the main action in a section. Use the secondary
variant when an action is available but should have less visual emphasis.

## Examples

<Canvas of={ButtonStories.Primary} />

## Controls

<Controls of={ButtonStories.Primary} />

This illustrates the structure, not a universal configuration recipe. Doc Block names and imports may vary with the Storybook release in your project. Confirm the MDX and Doc Blocks syntax against the documentation for that release before adopting it.

For content that is not tied to one component’s stories, author a standalone MDX documentation page and choose its title and navigation placement deliberately. Examples include a design principles guide, a token overview, or an onboarding page.

MDX’s framework boundary

Storybook’s MDX documentation renderer is React-based, even when the stories themselves use another supported framework. Account for that boundary when adding custom docs components: a component intended for the docs renderer may need to be React-compatible even if the UI library being documented is not React-based.

4. Decide what belongs in Autodocs and MDX

Question	Autodocs	MDX
Can the content be inferred from stories and metadata?	Good fit for generated examples and API information.	Use when authors need to explain what the metadata cannot express.
Is the page about one component?	A strong baseline for a component reference page.	Attach MDX to its stories when that component needs tailored guidance.
Does the guidance span the design system?	Individual component pages will not explain system-wide principles.	Use a standalone page for cross-component guidance, tokens, or onboarding.
Does the page need custom documentation components?	Generated pages may be enough without custom layout.	Useful for tailored layouts; account for the React-based docs renderer.

In practice, combine them: let Autodocs provide the consistent reference and use MDX to add rationale, usage guidance, and layouts where readers need more context.

5. Preview and build the documentation

Review the rendered documentation, not just the story source. Check that the examples render, the prose matches the behavior shown, and navigation makes the pages easy to find. Storybook supports a docs preview mode and a documentation build that writes output to storybook-static.

1. Start Storybook using the project’s existing development script.
2. Open the docs preview and review representative component pages and standalone guides.
3. Check that authored examples agree with the current component behavior and metadata.
4. Run the project’s Storybook documentation build script, or its configured build command.
5. Confirm the build output includes the expected docs pages in storybook-static.

Use the scripts already defined by your project rather than copying a command that may not match its package manager or Storybook version. Make rendered-docs review part of the team’s normal documentation workflow so changes to stories and metadata are reflected in the reference.

6. Share the system in consumer Storybooks when needed

If teams that consume your design system need to browse it from their own Storybook, evaluate package composition. It can expose a design system inside consumer Storybooks, and comparing composed versions can help show how a library evolves. This is a distribution choice: first decide whether a shared published documentation site meets the teams’ needs or whether the docs need to appear alongside their own stories.

7. Capture visual references for documentation

Storybook stories are useful visual references for documenting a system. A screenshot can also preserve a representative rendered state in a design review, issue, or written guide. Capture the state you intend to discuss, and note the viewport and relevant story state so readers can interpret the image.

For a manual browser capture, open the desired story, set the intended viewport, and use the browser’s screenshot or print workflow. For repeated captures, automate the browser with the tooling already used by your team, and make the story URL, viewport, and output format explicit. The result depends on the page being loaded and the state being ready before capture.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF; the example below saves a WebP screenshot. See the API documentation for options such as viewport, full-page capture, element selection, and wait conditions.

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

import requests

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

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://storybook.js.org'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

Replace the example URL with a publicly reachable Storybook story 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, and paid plans start at $5 for 3,000.

Sign up for 1,000 free screenshots a month, with no card required.

Troubleshooting

Symptom	Likely cause	What to do
No Autodocs page appears.	The stories are not tagged for Autodocs, or the global tag configuration is missing.	Add the autodocs tag to the relevant stories or enable it globally using the configuration for your installed Storybook version.
API or controls information is incomplete.	The relevant information is not represented in the component metadata Storybook can infer.	Review the component, args, argTypes, and parameters; add authored MDX for explanations that cannot be inferred.
An MDX page is not associated with the intended stories.	The page is standalone, or its Meta association does not point to the intended stories file.	For an attached page, use the appropriate Meta association and verify the imported CSF module. For a standalone guide, set its navigation placement deliberately.
A custom MDX component fails to render.	The docs renderer is React-based and the custom component may not fit that boundary.	Use a compatible docs component and check the MDX guidance for the project’s Storybook version.
A story renders differently from its written guidance.	The component or story changed while the prose became stale.	Review the rendered docs after changes and update the story or guidance so they agree.
A documentation build omits expected content.	The page may not be included or associated as intended, or the project may use a different build setup.	Preview the page in Storybook, check its MDX/story association, and run the documentation build configured by the project.
A screenshot shows a loading state or incomplete page.	The page was captured before the story finished loading or reached the desired state.	Use an explicit wait condition or delay where appropriate, and verify the story URL and state before capturing.

Performance, reliability, and cost considerations

• Keep the docs useful to navigate. Prefer representative stories over many redundant states. Clear story names and intentional page placement reduce the effort required to find the right example.
• Review generated and authored content together. Autodocs reflects available metadata; MDX can become stale if it describes behavior no longer shown by the stories. Review both when a component changes.
• Check version-specific behavior. The configuration and MDX examples depend on the installed Storybook release and framework. Use matching documentation rather than assuming one recipe applies everywhere.
• Choose screenshot scope deliberately. Full-page captures can preserve long pages; element capture can focus on a component. Wait for the relevant story state before capture to avoid recording an incomplete render.
• Budget repeated captures according to the service used. ScreenshotNeo offers a free tier of 1,000 shots per month and paid tiers from $5 for 3,000; its stated billing excludes bot checks, blank pages, failed loads, timeouts, and cache hits. Check the product docs for request options and current plan details.

FAQ

Can I use Autodocs and MDX together?

Yes. Use Autodocs for the consistent component reference and MDX for additional explanations, guidance, or a tailored page layout.

Does MDX only work with React components?

Storybook’s MDX documentation renderer is React-based, even when the stories use another supported framework. This matters when you create custom components for the docs page.

Can Storybook document guidance that is not about a component?

Yes. Standalone MDX pages can hold system-wide material such as onboarding, accessibility guidance, or design-token documentation.

How can consumer teams see the design system in their Storybook?

Evaluate package composition when the system needs to appear inside consumer Storybooks. It can also help teams compare composed library versions.