March 19, 2026

Documentation-First Design Systems

Whether you're building a design system from scratch or re-scoping an existing one, there's a natural temptation to jump straight into the build.

But I'd encourage you to slow down — just a little — and start by making and recording your foundational decisions first. This has always been good practice, but it's become significantly more important now that AI agents are part of the picture. The decisions you document aren't just for your team anymore — they're the foundation that AI tools will use to generate implementations, suggest patterns, and assist with adoption. A well-documented system is one that both humans and AI can consume correctly.

What that looks like will vary. For some teams, it means documenting everything up front: every naming convention, every token scale, every component API. For others, it means nailing down the big-picture decisions first and iterating from there as the system takes shape.

Either way, the goal is the same: work out the hard decisions while they're still easy to change.

Why start with decisions?

The most obvious benefit is that you'll catch inconsistencies before they become breaking changes. It's much easier to notice that you're calling the same concept "notification" in one place and "message" in another when you're looking at a document than when you're well into a build. Renaming a prop in a doc costs nothing. Renaming it in a published package costs a migration guide and a major version bump.

But there are other benefits that aren't immediately obvious:

It forces you to define your scope. When you sit down to document what the system will provide, you also have to decide what it won't provide. That boundary — between what the system owns and what consuming applications should build themselves — is one of the most important decisions you'll make, and it's one that rarely gets articulated until something goes wrong.

It creates alignment across disciplines. Designers, developers, and stakeholders often have different mental models of what a design system is. A written set of decisions gives everyone the same reference point. It's harder to disagree about implementation when the ground rules are already agreed upon.

It accelerates onboarding. New team members — and this increasingly includes AI agents — can ramp up faster when the rules of the system are documented. A well-documented system is easier to consume correctly.

It gives you something to evaluate against. As your system grows, you'll inevitably face decisions about whether to add a new component, change a naming pattern, or expand into a new technology. Having your original decisions documented means you're building on prior thinking, not starting from zero every time.

The checklist

What follows is a checklist of foundational decisions to work through before — or very early in — your build. These aren't exhaustive, and not all of them will apply to every system. But they represent the baseline decisions that, in my experience, are worth getting right early because they're expensive to change later.

I've organized them into four categories: Strategy & Governance, Conventions & Standards, Technical Decisions, and Build, Distribution & Documentation.

Strategy & Governance

These are the "what and why" decisions. They define the system's purpose, audience, and boundaries.

Define system scope

Before you decide how to build anything, decide what you're building and for whom.

Who are your users? Developers on your team? Across the organization? External consumers?
Who owns the system? A dedicated team, or shared ownership? Who has final say?
What is your governance model? How do decisions get made? Who approves new components or breaking changes?
Where do you draw the line? What does the system provide, and what should consuming applications build themselves? You'll revisit this over time, but you need a starting position.

Define content categories

How you organize your system's offerings affects how people find and use them.

How are you organizing and presenting your content? Your internal architecture doesn't have to match your public-facing documentation structure.
Should you use Atomic Design principles? Atomic Design is a useful mental model for building a system, but its terminology can confuse consumers.
What categories make sense for your users? Look at how established systems organize their content for inspiration:
- Foundations, Utilities, Components, Patterns
- Styles, Components, Patterns

My recommendation: use Atomic Design thinking during the design and build phase, but present content based on context and user expectations.

Define a contribution model

If your system will be consumed by multiple teams, you need a plan for how it grows.

How do new components get proposed? A request process, review board, or proposal template?
Who can contribute? Core team only, or can consuming teams submit components?
What are the acceptance criteria? Documentation, tests, accessibility review, design sign-off?
How do you handle requests that don't fit? A clear "no" path is just as important as a "yes" path.

Conventions & Standards

These decisions define how you talk about and structure things within the system. They seem small, but inconsistency here creates confusion that compounds over time.

Use consistent terminology

Decide early how you'll refer to things, and stick to it everywhere.

Choose one name for each concept. Is it "navigation" or "menu"? "Notification" or "message"? "Modal" or "dialog"? Pick one and use it everywhere.
Use consistent prop names. If multiple components accept a size prop, call it size everywhere — not size in one and variant in another.

Establish naming conventions

Naming conventions are one of the most tedious things to decide and one of the most painful to change later.

Are you prefixing CSS classes? A namespace prefix (like ds-button) prevents collisions with consuming applications.
What are your rules for abbreviations? Is it button or btn? breakpoint or bp? Decide once and apply it consistently.
How are you abbreviating size designations? Pick a format and use it everywhere:
- sm, md, lg, xl, 2xl
- small, medium, large, x-large, 2x-large
- S, M, L, XL, 2XL

Establish standard typography and spacing scales

These are the foundation that every component is built on. Getting them right early prevents a lot of rework.

Define these scales deliberately. Typography and spacing should come from intentional design decisions, not ad hoc values added as components are built.
Are these mathematical scales or curated values? A modular scale for type, a 4px/8px grid for spacing, or hand-picked values? Either approach works, but be intentional.
Which measurement units are you using? rem, px, em? It will likely vary based on context. Decide on conventions and document them.

Adopt design tokens

Design tokens are platform-agnostic representations of your design decisions — colors, spacing, typography, borders — stored in a format that can be translated into any technology your system supports.

Are you using design tokens? If your system serves more than one platform or toolkit, tokens are how you keep them in sync. They're the single source of truth that feeds your CSS, your Figma library, and anything else downstream.
What format are you using? The W3C Design Token Community Group spec is gaining traction and worth evaluating as a standard format.
How are tokens structured? Primitive tokens store raw values. Semantic tokens assign meaning (e.g., color.text.primary). Component tokens target specific components when more specificity is needed.
How are tokens distributed? Compiled to CSS custom properties, exported to JSON, synced to Figma variables? Decide how tokens flow from their source into the tools your team actually uses.

Establish accessibility standards

Accessibility shouldn't be an afterthought. Decide on your standards up front.

What WCAG conformance level are you targeting? WCAG 2.1 AA is the most common baseline as of this writing.
What are your testing expectations? Which tools (axe, Lighthouse, manual testing)? Are you running automated checks in CI? What needs to pass before a component ships?
How are you documenting accessibility? Keyboard interactions, screen reader expectations, required ARIA attributes?

Technical Decisions

These define the "how" — the technologies, tools, and approaches that shape your system's implementation.

Determine supported technologies

What you build and how many ways you build it have a huge impact on the system's complexity and maintenance cost.

Is there an associated Figma library? How does it stay in sync with the code? Who's responsible for updates?
How many frameworks are you supporting? The more you support, the more you need to separate what can be shared (tokens, CSS) from what needs framework-specific implementations.
Can redundancies be combined? Look for opportunities to reduce duplication across toolkits.
Are you providing an MCP server? An MCP (Model Context Protocol) server makes your system directly queryable by AI agents — component APIs, token values, usage guidelines, all on demand. It's quickly becoming a first-class part of a design system's technology stack.

Determine styling approach

Your CSS strategy affects how components are built, how they're consumed, and how much flexibility consumers have.

What's your overall styling strategy? Component-scoped styles, utility-first, global stylesheets, CSS-in-JS, or a hybrid? Each has tradeoffs for portability, scoping, and developer experience.
Do you need a preprocessor? Native CSS now supports nesting, container queries, and cascade layers. Sass and PostCSS are still widely used, but vanilla CSS may be sufficient depending on your needs.
How are you scoping styles? Naming conventions (BEM, SUIT CSS), CSS Modules, or framework-level scoping? This directly affects how portable your components are.
How do design tokens flow into your styles? CSS custom properties, generated utility classes? Decide how tokens get from their source format into the code your components actually use.

Determine the scope of your utility classes

If your system includes utility classes, be deliberate about how many you provide.

Provide only what's useful for successful implementation. A minimal set of well-chosen utilities (spacing, text alignment, visibility) gives consumers helpful shortcuts without enabling them to bypass the system.
Too many utilities create problems. An overly comprehensive utility layer makes it too easy to deviate from the design intent. Utilities should support the system, not undermine it.

Define browser and device support

This affects every technical decision downstream, from CSS features to JavaScript APIs.

What browsers and versions are you officially supporting? This determines what CSS and JS features are available to component authors.
What devices and screen sizes are you designing for? Define your breakpoints. Mobile-first or desktop-first?
How do you handle unsupported environments? Graceful degradation? Progressive enhancement?

Build, Distribution & Documentation

These decisions cover how the system gets from source code to consumers' hands, and how those consumers learn to use it.

Determine how tools are built and distributed

The build and distribution model affects how easy it is for teams to adopt and stay current with the system.

How will you build your toolkit(s)? Compiling tokens, bundling CSS, transpiling JavaScript?
Are you using Storybook or a similar tool? For development only, or as part of your public documentation?
How will you distribute? npm, Composer, a CDN, a private registry? Consider also providing an MCP server — it makes your system directly queryable by AI agents and is increasingly becoming a first-class distribution channel.
What's your versioning strategy? Semantic versioning is the standard. But also decide how you'll handle breaking changes — how much notice consumers get, how long deprecated features stick around, and whether you'll support multiple major versions.

Determine how your system will be documented

Documentation is what turns a collection of components into a system that people can actually use correctly.

Make it easy for users to follow the rules. If someone has to hunt for how to use a component, they'll guess — and they'll guess wrong.
Where will documentation live? Some teams maintain a dedicated documentation site. Others keep docs inline with the toolkit. Many do both — a public-facing site for guidelines and usage, and code-level docs for implementation details.
Define consistent documentation categories. Not every component will need every category, but the structure should be predictable. For example:
- Usage: When and why to use this component
- Implementation: How to use it (props, variants, code examples)
- Accessibility: Keyboard behavior, ARIA requirements, screen reader expectations
- Design: Figma links, spacing specs, visual guidelines
Write for all your consumers. This means writing for both humans and AI agents — more on that below.

Your documentation is now an API

If you'd asked me to write this checklist a year ago, the advice would have been largely the same — but the urgency would have been different. Documentation was always important. Now it's becoming a competitive advantage.

AI agents are increasingly part of how design systems get consumed. Developers use them to generate component implementations, write wrapper code, and scaffold new pages. And what those agents produce is only as good as the documentation they have access to. This shifts documentation from "nice to have for onboarding" to "the primary API for a growing segment of your users."

A few things change in practice:

Your documentation becomes machine-readable context. If prop definitions, variant options, code examples, and usage guidelines are clearly documented in a consistent structure, AI agents produce correct implementations. If they're scattered or missing, agents guess — and can create tech debt.

Consistency matters even more. Humans can figure out that size and buttonSize mean the same thing. AI agents are more literal. The naming and terminology decisions from the checklist above directly affect how well AI can work with your system.

Supported technologies may simplify. If AI agents can reliably generate framework-specific implementations from well-documented source components, you may not need to maintain as many toolkit variants. A single well-documented source of truth might be enough for AI to handle the translation layer.

Documentation structure becomes a prompting pattern. A consistent component documentation format — usage, implementation, accessibility, design — becomes a reliable pattern that AI agents can follow when generating implementations.

An MCP server becomes a core implementation. If you're not familiar with MCP (Model Context Protocol), it's a standard that lets AI agents query external tools and data sources directly. Building an MCP server for your design system means agents can look up component APIs, token values, and usage guidelines on demand — without needing your full documentation pre-loaded into context. I built one for my design system, and I consider it one of the primary implementations alongside the component toolkit itself.

The beauty of all this is that what makes documentation good for AI — clear structure, consistent terminology, concrete examples — also makes it better for humans.

Getting started

You don't have to answer every question on this checklist before writing your first component. But you should answer enough of them that your first component doesn't set a precedent you'll later regret.

Start with the decisions that are hardest to change: naming conventions, typography and spacing scales, styling approach, and system scope. These are the choices that get baked into every component you build, and changing them later means changing everything.

Then, as your system grows, revisit this checklist. The answers will evolve — and that's fine. The point isn't to get everything right on day one. The point is to make your decisions intentionally and write them down, so that when things do change, you're making informed updates rather than discovering assumptions you didn't know you'd made.

Design SystemsAI