Component page template
Use this structure for new and existing component-page drafts. Keep the relative section order. Omit an optional section only when research confirms that the component has nothing useful and specific to say there. The writer workflow owns draft paths, relative references, and draft-only frontmatter.
Replace every bracketed instruction before saving the page. Do not leave template markers in published content.
Frontmatter
Frontmatter rules
| Field | Rule |
|---|---|
title | Use the official component name. Required. |
description | Use one or two sentences to define the component and its main boundary. Required and visible to readers. |
synopsis | Summarise what the component is and the guidance the page covers. It must be more useful for retrieval than the description and must not repeat it verbatim. |
alternativeNames | Include only real terms that designers, developers, or users search for. Omit if there are no established alternatives. |
keywords | Include the component category, user task, important parts, states, behaviours, and close decision concepts. Avoid generic filler. |
hideRelatedPages | Use when the authored ## Related components table should replace the automatic related list. |
ignoreRelatedPages | Use instead when the automatic list should remain but must omit pages already represented in the authored table. |
renderAllChildPagesAsTabs | Use only when verified child pages, such as generated developer documentation, should render as tabs. Do not copy it automatically from Button. Omit the key entirely when it does not apply — never write renderAllChildPagesAsTabs: false. |
Navigation fields are conditional repository behaviour, not part of the content schema. Choose them from the page’s real child-page and related-page setup.
Complete skeleton
Section rules
Demo
Include the interactive demo when the component has an existing supported local integration. The
demo belongs before WhenToUse. Import only local authored demo wrappers; globally registered MDX
components need no import. When no integration exists, omit the import and return a supporting
implementation proposal instead of creating demo code.
When to use
Include a small set of non-overlapping user needs. Evidence determines the count; each visible rule
and its aiRule must add distinct value.
When not to use
Include this section when sibling components or ordinary HTML patterns create a meaningful choice. Link to existing MDS pages. Do not create a link to a route that does not exist. If an alternative has no MDS page, name it plainly and explain the boundary without a broken PageLink.
Usage guidance
This is the page’s centre of gravity. Start with the primary UX axis, then progress from default decisions to exceptions and advanced behaviour. Use imperative subsection headings. Use tables for structured comparisons and examples for consequential visual decisions.
Patterns
Patterns are recurring compositions or workflows, not individual properties. Omit this section if research finds no established composition.
Where the component sits is a pattern. Keep an existing placement section here, with its images, such as the main content area or inside another MDS component, when the source page has one. Do not drop it for lack of external research: placement among MDS components is an MDS decision.
Content guidance
Cover text the component owns: labels, helper text, errors, empty states, values, or action copy. Omit it for a component with no authored text surface. Link to shared content guidance rather than restating it.
States and feedback
List only implemented and relevant states. Describe what triggers each state, what it communicates, and how the user proceeds or recovers. Do not copy the standard state list unchanged.
Accessibility
Optional. Include this section only when the author or designer has something to do that the component does not do for them, such as label text, the tab order of interactive content inside the component, or contrast of custom content. Omit it when the only content would be built-in behaviour, such as keyboard operation the component already handles. Do not claim keyboard support, ARIA behaviour, focus management, or announcements without evidence.
Related components
Use a table with one concrete decision cue per linked component. Keep it consistent with WhenNotToUse, while allowing closely complementary components that are not alternatives.