In a design system's documentation site, what sections should every component page share, and why use one fixed template for all of them?
answer
- the same order on every page
- what, when, parts, variants
- API per platform
- accessibility and content guidance
- gaps become visible
basics
~20 sOverview, usage, anatomy, variants and states, API, accessibility and content guidance, in the same order on every page. A fixed template lets readers jump straight to what they need and makes missing sections obvious to authors.
solid answer
~40 sI would give every component page the same sections in the same order: an **overview** saying what it is with a live example; **usage**, meaning when to use it, when not to and what to use instead; **anatomy**, naming each part; **variants and states**; the **API** reference, switchable per platform; **accessibility**, covering built-in behaviour and what the consumer must still do; **content guidance** for labels and messages; and **related** components and patterns. One fixed template matters because readers learn the layout once and then jump straight to the section they need on any page. It also works as a **completeness check** for authors - an empty accessibility section is visible - and makes components comparable. Sections that do not apply say so rather than disappearing.
go deeper
Recall the standard sections - overview, usage, anatomy, variants and states, API, accessibility, content, related - and what question each answers.
Explain why a fixed template helps readers and authors, and how one page serves designers, engineers and several platforms without hiding anything.
Show how you would introduce or change a template across hundreds of existing pages, and enforce it through review without stalling contributions.
Weigh template rigidity against the needs of unusual components, and how the documentation structure signals what the organisation treats as essential.
## What a component page template is A **page template** is the fixed set of sections, in a fixed order, that every component page on a design system's documentation site follows. It is to documentation what a component is to interface: a reusable structure that makes each instance predictable. ## The sections and what each answers | Section | Question it answers | Typical content | Main reader | |---|---|---|---| | Overview | What is this? | one-sentence purpose, a live example | everyone | | Usage | When should I use it, and when not? | guidance, alternatives, do and don't examples | designers, product managers | | Anatomy | What are its parts called? | labelled diagram of each part | designers, engineers | | Variants and states | What forms does it take? | sizes, emphasis levels, states such as disabled or error | designers, engineers | | API | How do I build with it? | properties, events, slots, per platform | engineers | | Accessibility | What does it handle, and what must I do? | keyboard interaction, announcements, consumer obligations | everyone | | Content | What should the text say? | label length, tone, capitalisation, error message rules | writers, designers | | Related | What else should I look at? | similar components, patterns it appears in | everyone | The order follows the reader's journey: first decide whether this is the right component, then learn its shape, then build it, then check it is accessible and well written. ## Why one fixed template 1. **Predictability**: readers learn the layout once. On any page they can jump directly to the API or the accessibility section without scanning. 2. **Completeness**: a template makes gaps visible. If a page's accessibility section is empty, everyone can see it; with free-form pages, missing guidance is invisible. 3. **Comparability**: a designer choosing between two similar components can read the same sections side by side. 4. **Authoring speed**: new pages start from the template, and contributors know what is expected. 5. **Tooling**: consistent structure lets parts of the page, such as the API reference, be produced from the source code rather than written by hand. ## Serving several audiences and platforms One page serves designers, engineers and writers, on web and native mobile. Two common layouts: - **Tabs by discipline** (usage, design, code, accessibility): shorter views, but content on another tab can be missed; an engineer may never open the usage tab. - **One long page with a sticky table of contents**: everything visible and searchable in one place, but longer to scroll. Both are defensible. What matters is that **accessibility and usage are not hidden** from the people who most need them, and that platform differences are handled with a **platform switcher** on the API and implementation sections, so a native mobile engineer sees their platform's properties while shared guidance stays the same. ## Keeping the template lean - A section that does not apply is marked **not applicable**, with a reason, rather than removed; readers then know it was considered. - The template should be revised rarely and deliberately, since every change touches every page. - Extra sections for one unusual component are added below the standard ones, so the shared order is unchanged. ## Applying it On a museum ticketing kiosk team, a designer looking at the **ticket-type selector** reads the usage section to confirm it fits a single choice among adult, child and concession tickets, checks the anatomy to name its parts in the handoff, and points the engineer to the accessibility section for the keyboard and screen reader behaviour. The engineer switches the API section to the kiosk's platform. Neither reads the whole page, and neither has to hunt. ## Common mistakes - Free-form pages that each component owner structures differently. - An API reference with no usage guidance, so teams know how but not when. - Accessibility treated as optional and left out of the template. - Separate design and engineering sites with no shared page, so the two disciplines read different truths. - Changing the template's section order on some pages but not others during a gradual migration, so readers' learned navigation stops working.
- Should a component page split design and engineering content into tabs, or keep one long page?Either works if nothing essential is hidden. Tabs give shorter views but let readers skip the tab they most need, such as engineers missing usage guidance. A single page with a sticky table of contents keeps everything visible and searchable. Whichever you choose, keep accessibility and usage reachable by every reader and put platform differences behind a switcher.
- What should the template do when a section does not apply to a component?Keep the heading and say it does not apply, with a short reason - for example, a purely decorative divider has no keyboard interaction. Removing the section makes readers wonder whether it was forgotten, and it breaks the predictable order that lets them jump straight to a section.
- How does a fixed template help the system team, not only readers?It turns documentation into a checklist: reviewers can see at a glance which pages lack accessibility or content guidance. New contributors start from a known shape. And consistent structure lets parts such as the API reference be generated, reducing hand-maintained text.
saying these in an interview costs you the question
- Each component owner should structure their page however suits the component.
- An API reference is enough documentation for a component.
- Sections that do not apply should simply be deleted from that page.
- Designers and engineers are best served by separate sites with no shared page.
- Accessibility guidance belongs in a separate section of the site, not on component pages.