In a design system's documentation site, why separate foundations, components and patterns, and what belongs in each section?
answer
- three kinds of question
- rules, parts, recipes
- defined once, linked everywhere
- patterns combine components for a task
- entry points around the core three
basics
~20 sEach answers a different question. Foundations hold shared rules - color, type, spacing, motion, icons, accessibility principles. Components document each reusable part. Patterns show how parts combine for recurring tasks. Separating them lets readers find answers by the kind of question.
solid answer
~40 sA design-system site serves readers asking three different kinds of question, so it gets three sections. **Foundations** answer 'what are the rules?': color, typography, spacing, elevation, motion, iconography, content voice and accessibility principles, each defined once and referenced everywhere. **Components** answer 'how do I use this part?': one page per reusable component, like a button, a radio group or a date picker. **Patterns** answer 'how do I solve this task?': recurring problems that combine several components, such as empty states, error recovery or an idle-timeout warning. Around the core sit entry points - getting started per discipline and platform, resources, contribution and what's new. The split keeps each rule in one place and gives readers a predictable place to look for each kind of answer.
go deeper
Recall the three sections and the question each answers: foundations for shared rules, components for reusable parts, patterns for recurring tasks that combine parts.
Explain why rules are defined once and linked, why pattern guidance must not be buried in component pages, and how platform differences are handled inside pages.
Show how you would place ambiguous content, handle growth without duplication, and keep the structure stable enough that readers' learned navigation keeps working.
Weigh how much structure the site needs at the system's current scale, and how its architecture reflects what the system wants to be known for beyond a component list.
## Three sections for three questions A **design system documentation site** is the public face of a design system: the place designers, engineers, writers and product managers go to learn how to build with it. Its **information architecture** - how content is grouped, named and linked - decides whether readers find answers or give up and ask in chat. Most mature systems settle on three core sections because readers arrive with three kinds of question: | Section | Question it answers | Typical contents | |---|---|---| | Foundations | What are the shared rules? | color, typography, spacing and layout, elevation, motion, iconography, content voice, accessibility principles, design tokens | | Components | How do I use this reusable part? | one page per component: overview, usage, anatomy, API, accessibility | | Patterns | How do I solve this recurring task? | empty states, loading and error recovery, confirmation, onboarding, timeouts, search and filtering | ## Foundations Foundations are the rules every component and pattern obeys. They are **defined once** here and **linked** from component pages, rather than restated on each one. If the minimum text contrast or the spacing scale is described on forty component pages, it will eventually be described forty different ways. Foundations are also where the system's **design tokens** - named values for color, spacing, type and motion - are explained, so a web engineer, a native mobile engineer and a designer working in a design editor can each map the same rule into their own medium. A foundation page states the rule and its reason; the platforms differ only in how they express it. ## Components The components section is usually the largest and most visited. Each page documents one reusable part using a shared page template, so a reader who has learned one page can navigate any other. Component pages link to the foundations they use and to the patterns they appear in. ## Patterns Patterns are where many sites are weakest. A **pattern** documents a solution to a recurring task that spans several components. Take a museum ticketing kiosk. A kiosk team needs to know what happens when a visitor walks away mid-purchase. No single component answers that: it involves a dialog-like warning, a countdown, a way to continue and a reset to the start screen. That guidance belongs in an **idle-timeout pattern**, not buried in the page for any one of those components. Patterns are also where the system shows **judgement**: how to handle empty results, how to recover from an error, how to confirm without nagging. The same kiosk offers a second example: when a visitor picks a date with no free time slots, the screen needs an empty-state message, a suggestion of the nearest available date and a way back. That is an **empty-state pattern** shared with the museum's website, not a property of the calendar component. ## Around the core three Most sites also need: - **Getting started**, split by discipline (designers, engineers) and by platform (web, native mobile), because the first steps differ. - **Resources**: design library files, packages, icon downloads. - **Contribution**: how to propose or change something. - **What's new**: a changelog or release notes entry point. These are entry points; they route readers into the core three. ## Why not organise by team or platform? Two tempting alternatives work worse: 1. **By internal team** ('the tokens team's pages', 'the mobile team's pages') mirrors the org chart, which readers do not know and which changes. 2. **By platform at the top level** duplicates every component and foundation per platform. Platform differences are better handled **inside** a page - a platform switcher on the API section - so the shared guidance exists once. The three-way split is a convention, not a standard. Some systems add sections such as 'content' or 'tokens' at the top level. What matters is that each section answers a distinct question and the boundaries are stable. ## Common mistakes - Burying pattern guidance inside one component's page, so readers looking for the task never find it. - Copying foundation rules onto every component page instead of linking. - Giving a component and a pattern the same name, so readers cannot tell which page answers their question. - Top-level navigation that reflects how the system team is organised rather than what readers ask.
- Where should guidance go when a question spans several components, such as what a kiosk does when a visitor walks away mid-purchase?In a pattern page named for the task, such as idle timeout. It explains the whole flow and links to each component involved. Each component page links back to the pattern, so readers who start from a component still find the task guidance.
- Why should platform differences live inside pages rather than as separate top-level sections?Most guidance - when to use a component, its anatomy, its content rules - is the same on every platform. Top-level platform sections duplicate that guidance and let it drift. A platform switcher on the API and implementation parts keeps shared guidance in one place and shows only what genuinely differs.
The split works like a cookbook: foundations are the techniques chapter, components are the ingredients glossary, and patterns are the recipes that combine them for a particular dish.
saying these in an interview costs you the question
- Every component page should restate the full color and spacing rules it uses.
- Patterns are just big components and belong in the components section.
- The site's navigation should mirror the system team's internal structure.
- Each platform needs its own complete copy of the documentation site.
- Foundations are only for designers, so engineers can skip that section.