Design System Documentation as a Product
Good documentation can be the difference between a design system that thrives and one that gets ignored. It’s not just a place to dump information—it’s a product in itself. When we started thinking about documentation as an internal product, everything changed. Adoption increased, questions decreased, and teams started working more consistently across disciplines.
In this post, I’ll share best practices and lessons we learned while documenting our design system, Base UI—what worked, what didn’t, and how we’re continuing to evolve it.
📖 Start with Clear, Structured Content
The first step was structuring our documentation so it’s easy to understand at a glance. We broke down our content into three main categories:
Components: Detailed pages about how individual components are designed, behave, and can be used.
Foundation: Our guiding principles, tokens, brand guidelines, and how Base UI is built.
How to use Base UI: Practical guides for using and contributing to the system.
This simple structure helped users find what they needed without wading through long, undifferentiated pages. We also prioritized a visible, persistent side navigation that shows the full site structure—so even a first-time visitor can grasp the system at a glance. Clear navigation helps users feel grounded and confident as they explore.
🧩 Component Documentation = Clear & Comprehensive
Component documentation quickly became the most frequently accessed part of our site, and also the most important. It’s where designers and developers go to understand how to use the building blocks of the system. Early on, we conducted usability testing and interviews with our users to make sure we were providing the right level of detail in the right places.
We learned that it’s better to err on the side of more information than too little. It’s much easier for a user to skip sections they don’t need than to reach out to the design systems team for clarification every time they’re unsure. Here’s how we structured our component docs:
Live Code Examples
We embedded real, working examples from Storybook. These weren’t static screenshots—they included theme switchers and responsive behavior, so users could interact with components and see how they behave in different contexts. We even created a dedicated page in Storybook that highlights common use cases and edge cases.Component Anatomy
Each component page starts with a labeled visual that shows the structure of the component and any nested components it uses. We then describe what the component does, when it should be used, and whether any parts of it are optional. This section is especially helpful for designers during early stages of a build.States and Variations
We documented every state—default, hover, active, and disabled—and grouped them visually using tabs. Variants like size, layout, and theme options were also included. Tabs helped us organize this dense content in a way that wasn’t overwhelming.Responsive Behaviors
For components with built-in responsive logic—like our announcement banner—we annotated how the component adapts across breakpoints. This saved users from digging into the code or manually resizing their browser to figure it out.Usage Guidelines
This section was about providing practical tips and guardrails. We included clear dos and don’ts, as well as guidance on when to use similar components (like when to choose a carousel over tabs). We also added best practices for assets, content length, and tone.Props, API, and Accessibility
We included a comprehensive list of configurable props, along with usage examples. For accessibility, we detailed ARIA roles, screen reader behavior, and keyboard navigation patterns. This ensured that accessibility wasn’t an afterthought—it was built into the way we talked about components.Linked Components and Token Annotations
We cross-linked related components and clearly showed dependencies. For example, if a component relied on a shared utility or wrapper, we linked to it. We also annotated which design tokens were used—and noted a future improvement: showing token inheritance more clearly, especially when a semantic token referenced a global one (something Google’s Material documentation does well).
Our goal was to give users everything they needed to understand and use a component without needing to inspect code or Slack the design systems team.
🎨 Foundation = Understand Behind-the-scene
The Foundation section is where we shared the thoughts and logic behind the system. It includes:
An overview of the design system: what it is, why it exists, and how it helps teams build faster and more consistently.
Our guiding principles: simple, reusable, accessible, and scalable.
Links to external brand guidelines (which we plan to integrate directly into the site later).
A breakdown of how Base UI is built:
What makes up a design system (components, tokens, guidelines, etc.)
Tokens 101: definitions, use cases, and examples
Naming conventions for tokens
How design and code stay connected
Versioning process and update cadence
Concepts like “props” and “slots,” explained clearly for non-engineers
This section is especially useful for onboarding new team members and giving stakeholders a sense of how Base UI works behind the scenes.
🛠 “How To” Guides = Easy to Follow
We realized early on that not everyone comes in with the same level of experience or familiarity with design systems. That’s why it was important to clearly document a series of tutorials that team members could follow at their own pace, without needing to schedule a live walkthrough each time.
How to Use Base UI
We created a set of how-to guides covering everything from environment setup to accessing the design system in Figma and Storybook. Setting up the environment can often be a frustrating first step, so having a step-by-step guide helped reduce that friction and gave people more confidence.How to access the system (links to Figma and Storybook): We provided direct links and instructions for accessing our core resources. Since setup can be tedious, this guide was designed to be as straightforward as possible.
How to use Figma library and Tokens Studio: Because our components are token-based and tightly integrated with code, using tools like Tokens Studio was a new concept for many designers. We found that short video tutorials worked especially well in showing how everything connects across design and development.
Guidelines for customizing components: One of the most common questions we got was: “How much can I customize this component?” By documenting our customization principles and where flexibility was allowed, we were able to reduce one-off support while giving teams more clarity and autonomy.
How to Design with Base UI
Designing with Base UI, especially when it came to using the grid, spacing, and tokens, generated a lot of questions. After hearing similar issues during office hours, we put together reference docs to serve as a self-service resource. These resources became an essential reference for designers across product teams, especially for new joiners or teams designing something from scratch.Best practices for building UI using system components
Layout and spacing rules using the grid system
Using the right typography and color tokens
How to Contribute to Base UI
Using Base UI in product work is one thing—but contributing new components or improvements back into the system is another. We needed to define what “designing for a design system” actually means, and set up a clear, repeatable process for contributions. We documented:What it means to design for a design system
The workflow for submitting component requests
Our review and approval process
Writing these guides turned out to be more than just documentation—it helped align our team internally. It sparked productive conversations about what was working, what needed improvement, and how we could better support contributors.
🚨 Keep It Up-to-Date and Reliable
One of the biggest risks with documentation is that it becomes outdated. To stay ahead of this, we implemented a few routines:
Each page includes a visible “last updated” date
We maintain a changelog that explains what changed, why, and how it impacts teams
We run quarterly audits to review key pages and flag outdated content
This kind of transparency builds trust with users and gives them confidence that they’re looking at the most accurate information.
👋 Being Transparent About the Team
We also included a simple page explaining who maintains the design system, how to contact us, and what’s on the roadmap. It might seem minor, but this helped new team members feel more connected and confident about reaching out. It also set clear expectations for how our team supports Base UI.
💡 Tips to Make Documentation Effective and Usable
Documentation is never “done.” Here are a few things we’ve learned to keep it useful over time:
Test your docs like a product: We ran usability tests to make sure component pages were easy to understand, and plan to collect feedback quarterly to identify pain points.
Use visuals and videos: Not everything needs to be a paragraph. Short videos and annotated diagrams go a long way in helping users grasp complex ideas quickly.
Documentation is part of your communication plan: Docs alone won’t solve everything. Pair them with roadshows, Slack updates, and demos to keep the system top-of-mind.
Use your docs to spark conversations: When we published the first version of our “how to use Base UI” guide, it immediately got the team talking about what could be improved. It brought alignment and surfaced assumptions we didn’t know we had.
📌 Conclusion: Documentation Matters
Design system documentation isn’t just a support tool—it’s part of your product. When it’s clear, accessible, and thoughtfully maintained, it empowers teams to move faster and with more confidence.
Treat your documentation like a product, and your team will treat it like one too.