How to document design system components

If you’re building a product, you’ll no doubt be familiar with the concept of design systems and component libraries. Using a predefined “set” of components allows users to more easily and more efficiently develop user interface (UI) features that are on brand and meet accessibility requirements.

Components are often the most important part of any design system. Without them, your product may end up looking like an engineer designed it — and no one wants that!

Component documentation often lives online alongside higher level brand guidelines but component documentation dives a little deeper into how to configure and use components.

Design system vs component library: a quick aside

A design system is a set of fundamental rules that components (among other things) adhere to. Components are an important part of design systems, and can also exist outside of design systems as component libraries, like Material UI.

A design system is typically made up of design tokens. These can include values for colors, padding, margin, spacing, typography font sizes and border radii.

When using a component it may never be known which design tokens a component uses, but rest assured, under the hood a lot of thought will have gone into creating tokens that meet brand guidelines and work well when composed with other elements from the design system.

For example, a simple button will likely expose a prop named variant(or similar).

<Button variant='secondary'>click me</Button>

The variant prop will often accept values such as primary, secondary, or ghost.

At the component usage level there’s no need to know what hex value secondary relates to, but it will have been defined and explained in another area of the design system’s documentation.

This approach may apply to font families too where values such as heading, highlight or text will be used in place of the actual font-family name.

The general idea behind naming properties that map back to design tokens is to avoid confusion when changes occur.

For example, if the variant prop accepted red, blue and green, and later down the line, brand guidelines removed red from the color palette, or changed red to orange, changes to the application using the component would be required.

Best practices for component documentation

We’ve covered some basic principles of design systems and tokens, but there are many more things to consider when documenting components. Here’s a list of some best practices to keep in mind.

As with any site or application, navigation is important. In design system documentation, components should be considered as first-class entities. You can see from the below example taken from shadcn/ui documentation that there’s a link in both the top, and side navigation to the components section.

shadcn/ui component documentation

In the shadcn/ui documenation, users can see links to the components section in both the top and side navigation.

Consistent terminology

Naming things is hard! And as component documentation grows it can be difficult to ensure consistency among prop names, prop types, prop descriptions and even the order props are displayed within prop tables. But as you know, consistency is key.

prop tables documentation

In this table, users can see the naming conventions for prop names, prop types, and prop descriptions.

Prop names

One common practice when creating prop names is to use linking verbs.

For example, to set a button to disabled, the prop would be named isDisabled. This can also be applied to other prop names that might exist on other types of components, e.g. hasError, isLoading.

Using consistent linking verbs across all components within a system can greatly improve the developer experience. It’s also important to use consistent casing (in this case camelCase), e.g. isDisabled not isdisabled.

Prop types

Prop syntax changes from framework to framework. string props can be encapsulated using quote marks, whereas boolean props are encapsulated using curly braces. e.g.

<TextField value="some value">some text<TextField>
<TextField isDisabled={true}>some text<TextField>

As such, it’s important to document which primitive type the prop uses.

Prop descriptions

What each prop does can greatly differ from component to component, but it’s important to always include a description that is short and to the point.

It’s also important to use consistent grouping. The prop table for e.g. a button, should (where possible), be ordered the same way as an e.g. TextInput component. You could consider grouping by primitive type, or by linking verbs, or perhaps alphabetically.

Prop tables misc

It’s also a good idea to document any default values a component may have, or if a prop is required or optional, this can either be denoted by an asterisk or by adding a new column to the table.

Component usage context and rationale

While many common components are simply styled versions of their underlying HTML elements, newly introduced interface elements have emerged over the years. One such example is the Floating Action Button, or FAB introduced by Material Design ~2104.

floating action button by Material Design

The Floating Action Button in the Material Design docs provides details and recommendations on how to use it.

In such cases it’s important to provide more detailed information about the component’s intended usage. For example, this excerpt in the MUI docs explains that a FAB is only to be used if it’s the most suitable way to present a screen’s primary action, and that only one FAB is to be used per screen.

Visual examples

We’ve spoken a lot about prop documentation and written explanations, but understandably, being able to visually see a component is equally as important.

It’s common practice to visually render the component in the documentation then, below, show a code snippet that represents what’s seen on screen.

component rendered in documentation

By showing the code snippet below the component, the user is able to see both the code and what will appear on the screen.

Depending on which frameworks a component has been designed to work with can determine which code snippets to show. React code snippets would be slightly different to Solid and Vue. Providing tabbed code snippets can help users find the snippet relevant to their framework / usage.

Variation states

Include a section or page that aims to document “All” variants of a given component. This can provide a better overview of what variations are available for each component.

button variations in Storybook documentation

Users are able to see both the variants of each Button and the corresponding code snippet.

As before with the visual examples, it’s often good practice to include code snippets for each of the variants under the visual render.


The accessibility statement outlined by brand guidelines will determine which level of accessibility components should meet. Some industries, banking, government, etc. will need to adhere to higher WCAG rankings to meet legal requirements. An AA ranking is typically an acceptable level to work towards.

Storybook documentation accessibility plugin

In this example, the user can see the four accesibility passes in the plugin.

Adding an accessibility plugin to your documentation can highlight accessibility passes or fails together with the WCAG ranking the component conforms to.

Version control

For all the reasons version control exists in software development are the reasons it’s important to detail in your component library documentation. It’s quite likely a user will be reading the documentation for the latest version, but have a previous version installed in their development environment.

MUI documentation version 5.15.15

By including version control, the user will know that this documentation is for version 5.15.15.

In some cases it might even be desirable to have multiple versions of the documentation available. The MUI documentation allows users to select from a dropdown menu and select which version of the documentation they’d like to see. It’s also good practice to include a link to the changelog allowing users to see the changes between versions.

User feedback and open-source collaboration

Mistakes happen. Even with the best intentions, there are little things that slip the net. These could be as a result of human error, or perhaps when more detailed explanations of component usage would be helpful.

Discord, Twitter, and GitHub links on Radix docs

On the Radix documentation, the user has the option to join Discord, Twitter, and GitHub to seek additional help.

Invite collaboration and include a page somewhere in your documentation that explains how users can contact the maintainers to ask questions, or a link to the repository in cases where an issue should be filed.

Design resources

Code is great, but there are occasions where users might need access to the design files. This might be to create a mockup for another team, or to perhaps suggest ways in which a component could support a new feature.

Design resources on Ant Design docs

In the Ant Design docs, users are easily able to see and navigate to some source files that can be helpful for their projects.

Similar to the collaboration page, create a page somewhere with links to the source files. In some instances you might be able to provide design files in multiple formats, Sketch, Figma, Adobe XD etc.

Examples of great component documentation

Here’s a list of the documentation sites we’ve referenced within this guide but there are many more great examples here: Design Systems Gallery.

  • MUI — MUI offers a comprehensive suite of free UI tools to help you ship new features faster. Start with Material UI, our fully-loaded component library, or bring your own design system to our production-ready components.
  • Radix UI — An open source component library optimized for fast development, easy maintenance, and accessibility. Just import and go—no configuration required.
  • React Aria — Craft world-class accessible components with custom styles. Over 40 components with built-in behavior, adaptive interactions, top-tier accessibility, and internationalization out of the box, ready for your styles.
  • shadcn/ui — Beautifully designed components that you can copy and paste into your apps. Accessible. Customizable. Open Source.
  • Ark UI — Ark UI is a headless library for building reusable, scalable Design Systems that works for a wide range of JS frameworks.
  • Ant Design — A React UI library that provides a set of high-quality components and guidelines for building user interfaces in web applications. Ant Design aims to improve efficiency and consistency in UI development by offering ready-to-use components with extensive customization options.

Building interactive component documentation with StackBlitz

All of the examples we’ve shown so far are effectively “read only”, and while good documentation will demonstrate component usage for individual components, it can be hard to document every permutation of every component when composed with other components from the system.

In these cases, “interactive playgrounds” can really help users understand how to compose the different parts of the system to create larger UI features.

But “interactive playgrounds” are not only good for users, they can also prove very helpful in instances where a reproduction repo might be required when opening an issue. Adding a link directly to the “problem” component can help library maintainers find the root cause of the bug, faster!

They can also help with onboarding and adoption and provide a smoother, shallower on ramp for developers looking to get started with a component libary. Adding a link in your documentation to a pre-configured development environment, with the dependencies installed, can really improve the getting started developer journey.

And it’s here where StackBlitz can help!

Using StackBlitz you’re able to add a link to your documentation that will crack open a new StackBlitz development environment (many frameworks are supported) with all the component library dependencies installed.

From here users are able to compose complete features using components from the library. In the below example I’ve composed MUI’s Grid, Card, CardContent, Typography, CardAction and Button components to create a grid displaying movie information.

Grid displaying movie information

Using StackBlitz, we composed MUI’s Grid, Card, CardContent, Typography, CardAction and Button components to quickly spin up a grid dispaying movie information.

To create this, it took literally seconds, and could be very easily shared with members of the team for feedback. Moreover, StackBlitz updates in real time so, should the situation arise where a colleague wishes to “hop on a call to discuss” and make changes, it could all be refactored right there and then.

Compare that to the standard approach of building a feature, creating a PR, waiting for a build to succeed, then sending a link to a staging environment, awaiting and then addressing feedback… then repeat the whole cycle again. By using the StackBlitz SDK that links to an interactive playground, you can speed this entire process up considerably.

How to build interactive component documentation with StackBlitz

The StackBlitz JavaScript SDK can be used to link to preconfigured StackBlitz environments with the click of a button, right there from your documentation.

StackBlitz button in SDK

By clicking the StackBlitz button the user can open up a StackBlitz environment and get to work.

To open a StackBlitz environment with the MUI Grid component already set up and ready to go you could do something like this.

import sdk from '@stackblitz/sdk';

document.getElementById('button').addEventListener('click', () => {
  sdk.openProjectId('react-drvf85', {
    newWindow: true,
    view: 'preview',

This would open the following preconfigured StackBlitz project in a new browser window.

The StackBlitz SDK

Here’s an example from the Porsche Design System where StackBlitz has been used in component library documentation.

The Porsche documentation displays an “Edit in StackBlitz” button under each component. Clicking it will open a new StackBlitz environment displaying the same Button components from the docs page.

Button showing Edit in StackBlitz on Porsche Design System

When the user clicks the Edit in StackBlitz button, it opens a new StackBlitz environment that users can start working in.

WebContainer API

The StackBlitz SDK can be used in other ways too! A great example from the Svelte team utilizes our WebContainer API, which is the same StackBlitz development environment in the browser, and can be integrated as part of onboarding guides, or interactive tutorials.

StackBlitz development environment on Svelte docs

In this example from the Svelte team, users can start working directly in docs using the WebContainer API.

Final thoughts

I believe StackBlitz is the perfect partner for component documentation. There are many tools out there that will help you build a great documentation site, and by implementing some of the best practices mentioned in this article you’ll set your users up for success. But why stop there?

Add StackBlitz to the mix and take your documentation to the next level. If you’re keen to know more, try out StackBlitz today.

Paul Scanlon Guest Author
Product Marketer / Developer Advocate / Technical Writer
Explore more from StackBlitz

Subscribe to StackBlitz Updates

A newsletter from StackBlitz covering engineering achievements, product features, and updates from the community.

Using StackBlitz at work?

Create in-browser preview apps for every issue or pull request, share private templates with your org, manage your design system with zero overhead, and more.

Try StackBlitz Teams