The key sections of a design system
Learn

The key sections of a design system

Author Avatar
Written by
Aug 21, 2026

Good documentation for a design system starts with knowing what should be in it.

A lot of documentation gets built without that step. Teams work through whatever feels urgent, finish one section, start the next. The result is a docs site that covers buttons in exhaustive detail but never explains the principles those buttons were built around, or one where principles are written eloquently while the patterns they're meant to govern stay undocumented.

This article is the inventory. It walks through the sections a well-documented design system contains, explains why each one earns its place, and ends with a checklist you can use to audit your own docs.

The shape of a well-documented design system

Most design systems share the same rough hierarchy, even when section names differ between teams.

At the bottom are foundations: color, typography, spacing, iconography, motion. The design decisions everything else inherits from.

Components sit on top of foundations. Buttons, inputs, modals, navigation, the reusable building blocks of your interface. Components reference foundations and compose them into something you can drop into a screen.

Patterns combine multiple components into recurring solutions: forms, search results, empty states, sign-in flows. This is where the system answers "how should this kind of screen behave?" rather than "what does this individual element look like?"

Wrapping all of it, principles and content guidelines explain how the system thinks about design and how it speaks. Principles shape what gets added. Content guidelines shape what users read.

Cutting across everything, a getting started layer onboards new users, surfaces contribution guidance, and makes the rest of the documentation discoverable.

The sections below walk through each piece in turn.

Foundations

Foundations are the design decisions everything else is built on. Document them well and every component page that follows benefits.

Color

Cover your palette with names, values, and the role each color plays. A list of swatches isn't enough on its own; the reader also needs to know which colors are sanctioned for primary actions, surfaces, borders, and error states. Surface that through token names like color-action-primary and explain when each should be used.

Document accessibility alongside the values: contrast ratios, WCAG levels, and the pairings to avoid. Color documentation that doesn't carry its accessibility implications is half a job.

Typography

Cover families, weights, sizes, and line heights. Show each size visually rather than asking the reader to imagine the difference between 18px and 20px from numbers alone. Pair each visual with the semantic role (heading 1, body large, caption) so the reader knows which to reach for in which context.

If your typography uses composite tokens that bundle size, weight, and line height into a single token, document the composition explicitly so the reader doesn't have to infer it.

Spacing

Show your spacing scale visually. The scale matters more than the individual values: readers want to know the system's rhythm, not what 24px looks like in isolation. Pair the scale with semantic tokens (space-component-padding, space-layout-section) and a few worked examples of how to apply them.

Spacing is the foundation people most often hardcode, because the documentation rarely makes the alternative easy enough to reach for.

Iconography

Provide a searchable grid of every icon plus rules for sizing, color, and usage. If you have a custom icon style, document the guidelines so contributors can extend the set consistently. Most teams underdocument this and end up with icons drifting from the established style within a year.

Motion

Document durations, easings, and the principles behind when you use motion and when you don't. Motion is often the most neglected foundation because it's the hardest to capture on a static page. Three or four documented durations, an example of each in action, and a short note on when to use them is enough for most teams.

If your foundations are stored as design tokens, the companion design tokens guide covers token architecture in depth.

Components

Components are the part of the system most people interact with most often, and the component library is where the bulk of your documentation pages live.

A component library section needs three things at the index level: a way to browse all available components, a search that works, and a clear visual indication of each component's status (alpha, beta, stable, deprecated). Beyond that, the work lives on the individual component pages.

Article 03 walks through what a single component page should contain, the order the sections should appear in, and how to write each part. The two articles work together. This one tells you that components belong in your documentation. Article 03 tells you what goes on each component page.

A few decisions worth making at the section level. How to group components: by type (inputs, layout, feedback, navigation) is the most common approach and usually the most discoverable, while atomic-design-style grouping (atoms, molecules, organisms) sounds rigorous but rarely matches how people search. Whether to surface every variant on a separate page or fold variants into the parent component page: the default should be folding variants in, since most readers reach for a "button" first and discover the variants after. And how to handle composite components that wrap simpler ones: document the composite separately if it has a distinct purpose, reference the simpler one inside if not.

Patterns

A pattern is a recurring solution that spans multiple components. A sign-in flow that uses a card, two inputs, a primary button, and a help link is a pattern. A search results page that combines a search input, a filter sidebar, a results list, and pagination is a pattern.

Patterns exist because component documentation alone can't answer "how should this kind of screen behave?" Each individual component is documented in isolation, but the combinations are where the design system actually shapes the product. Pattern pages fill the gap between component documentation and full screens.

A pattern page usually contains the problem the pattern solves, the recommended solution, a worked visual example, the components involved, and any rules about how those components fit together (spacing between elements, hierarchy of actions, common variations).

Not every multi-component composition deserves a pattern page. The bar to set: a pattern earns its own documentation when teams keep building variations of the same thing, and the inconsistency is starting to show in the product. If three teams have built sign-in flows that work in three different ways, that's a sign the pattern needs documentation.

Article 05 covers patterns in depth, including when component docs are enough and when a pattern deserves its own page.

Content guidelines

Voice, tone, grammar, and the small but high-volume copy decisions: button labels, error messages, empty states, microcopy. Content is the layer of the system most teams pretend doesn't need documentation, and it's often where the system's inconsistency is most visible to users.

A content guidelines section covers the brand voice in plain language, with example phrases that exemplify it and ones that don't. It covers tone variations across contexts (a confirmation modal speaks differently from a marketing banner). And it sets specific rules for the recurring copy patterns in your product: button labels, error messages, empty states, success messages, tooltips, microcopy.

The mistake to avoid is publishing a voice document that's all adjectives ("friendly, confident, human, clear") with no examples. Adjectives don't shift behavior. Worked examples and side-by-side comparisons do.

Article 07 covers content guidelines in depth, including how to scope a content section when you don't have a content designer on the team.

Design principles

Design principles are the rules that explain how the system thinks about design. They're the most-skipped section in most documentation, and when they do get written, they're often the most decorative.

The problem with most design principles is that they don't make decisions. "Be human." "Be clear." "Be consistent." These read well on a slide deck and provide no guidance when two designers disagree about whether a particular pattern is "clear enough."

A useful design principle is one a designer or developer can cite to settle a real disagreement. "Prefer recognition over recall" tells you to surface options rather than asking users to remember labels. "Default to defaults" tells you not to add configuration knobs without a reason. Both are specific enough to apply.

Document principles with examples of how they've been applied in real components and patterns. If you can't find an example of a principle being used to make a decision, the principle probably isn't real. Three to five principles is plenty for most teams. Ten is usually too many for anyone to remember.

Getting started

Every documentation site needs a getting-started section, and most don't have one.

This layer answers the questions a new user asks in their first ten minutes. Where do I find the components? How do I install the library in my project? How do I propose a change? Who do I ask if something's wrong? What's the system's status, is everything stable, or are we still in beta?

Three pages usually cover it. One for designers, pointing to the Figma library and setting expectations for how it should be used. One for developers, with install steps, supported frameworks, and where the code lives. And a contributing page that walks through how to propose a change, who reviews it, and the cadence.

This is also where operational information lives that doesn't fit elsewhere: the system's overall status, a changelog, the team's roadmap or planned work, and a way to contact the team. Treating these as second-class makes the rest of the documentation harder to use.

A design system documentation checklist

For a system to be usefully documented, the sections below should be present in some form. Use this as a checklist to audit what you have and identify the gaps.

Foundations

  • Color palette with values, names, and roles
  • Accessibility notes for color (contrast, WCAG levels)
  • Typography with sizes shown visually and tied to semantic roles
  • Spacing scale with semantic tokens
  • Icon set with sizing, color, and usage rules
  • Motion durations, easings, and usage principles

Components

  • An index page with browse, search, and status indicators
  • A page per component following a consistent template
  • Status labels (alpha/beta/stable/deprecated) on every component

Patterns

  • Pages for the multi-component patterns your team uses repeatedly
  • Cross-links from pattern pages to the components they reference

Content guidelines

  • Voice and tone with examples, not just adjectives
  • Rules for recurring copy patterns (buttons, errors, empty states, tooltips)

Design principles

  • Three to five principles, each with a worked example of how it's been applied

Getting started

  • An onboarding page for designers
  • An onboarding page for developers
  • A contribution guide
  • System status, changelog, and team contact

Treat this list as the bar, not the ceiling. Most systems will add to it. Few should be missing items from it.

What to prioritize when you can't do it all

You probably won't be able to document everything at once. Here's the order most systems should work in.

Foundations first. They have the highest leverage because every component page that follows references them. A documented color palette and spacing scale change how the rest of the documentation reads.

A handful of components next. Pick the ones your teams use most often and document them well, following the template in Article 03. Five good component pages teach the template, and the rest of the library goes faster once the pattern is established.

Getting started and contribution pages third. Without these, even good component documentation can't onboard new users.

Patterns, principles, and content guidelines fourth. These compound the value of what's already documented but don't unblock anyone the same way the first three do.

The mistake to avoid is trying to write everything at low quality. A small, well-documented system outperforms a large system documented thinly. Adoption follows quality, not coverage.

Where to go next

This article maps the territory. Several other articles in the guide go deeper on individual sections.

Article 03 (How to document a design system component) covers the structure of an individual component page, which is where most of your documentation work will live.

Article 05 (Documenting design system patterns) covers when a pattern deserves its own documentation and how to write a pattern page.

Article 07 (Content guidelines in a design system) covers the writing layer in detail.

Article 10 (How to structure your documentation) covers the meta question of how to organize all these sections into a navigable site.

Author Avatar
Try zeroheight
The design systems platform that keeps teams and agents in sync
Start for free
Share this post