Two pages use the same collapsible block. One hides optional source notes; the other hides the instruction every reviewer needs. Matching borders have not made the behavior consistent. A design system documentation template should explain where a component belongs, what its states mean and what a consumer must preserve.
Document the usage rule beside a working specimen and its source. The original Review Notes 0.1 example below has a visible instruction and two independent reference disclosures. Its small specification connects usage, named style values, markup, state checks and change notes. It is a teaching system, not an export from a commercial design tool.
Open the complete example · Download the full HTML source
Give the system and its records an identity
Start with the system's purpose, the version being documented and the application or document that uses it. Name the maintained source and responsible owner when known. An attractive component gallery without that context can leave a team copying a specimen whose relationship to its current code is unclear.
Our original system is for static editorial review pages. Record RN-01 is the required instruction; RN-02 is the optional reference disclosure. The demonstration uses version 0.1. Actual organizational owner, repository release and approval reference are not supplied. The version identifies this authored specimen, not a real team's adopted standard.
Keep a component inventory with a stable ID, name, purpose, source reference and documented version. Add components as they become real, rather than filling a template with invented controls or unsupported variants.
Name the shared values and their purpose
The specification records three original CSS values: --rn-ink is #20394d for text, --rn-gap is 16px for the specimen's section spacing, and --rn-focus is #7c2d12 for its focus outline. The example uses those values; the document does not describe a different palette from the one a consumer receives.
Record meaning as well as a value. A future maintainer should know whether a change affects spacing, text or focus indication. The CSS variables guide explains the code mechanism; this record explains the contract your consumers are relying on. These chosen colors are not a claim of an accessibility certification or a complete theme.
State when a component should stay out
RN-01 keeps the review instruction visible: “Read the review scope before commenting.” RN-02 contains optional reference material that a reader can open when needed. The instruction does not move inside the disclosure just because the two blocks look related.
The GOV.UK Design System's details guidance documents both when to use the component and when not to hide information most users need. That distinction informs this authored usage rule. We are not copying GOV.UK's component styling, macros or example content.
Give each component a positive use case and a concrete misuse. “Use for optional source context” and “Do not conceal the required review instruction” let a reviewer assess a page. “Use consistently” supplies less help with that decision.
Describe markup and states that someone can check
RN-02 uses native details and summary elements. Its contract requires a descriptive summary and the supplied reference content. MDN's details reference describes the disclosure and its open attribute: the attribute's presence opens it; its absence leaves it closed by default.
The two specimen disclosures begin closed and open independently. Opening Reference notes must leave Implementation notes closed. Closing either preserves its supplied content for the next opening. The required instruction remains visible throughout. The HTML accordion guide covers the element itself; this documentation records the system-specific choice to keep these references independent.
Write expected checks before recording observations. Include the initial state, opening and closing each instance, unchanged neighboring content, narrow-screen reading and visible focus. The current browser receipts establish only the behaviors actually exercised. Keyboard activation, assistive technology and other browsers need their own observations before you call those checks complete.
Keep changes connected to affected pages
The filled specification includes a change-note scaffold: changed rule or value, reason, affected consumers, required checks and actual release reference. Leave a release or owner blank when it has not been supplied. Editing this page does not update every page that previously copied its CSS.
For a real change, identify which consumers use RN-02 and rerun the relevant checks on their actual pages. A spacing edit and a change to which content may be hidden need different reviews. Preserve the previous specification so someone can understand the difference.
Create a design system documentation record from our actual sources.
System purpose, version, owner and maintained source: [PASTE]
Shared style names, values and intended meanings: [PASTE]
Component IDs, usage rules, required markup and allowed states: [PASTE]
Known misuse, consumer pages and observed test results: [PASTE]
Proposed changes and actual release evidence, if any: [PASTE]
Return a filled Markdown specification and a self-contained HTML
reference with working specimens and complete source. Keep expected
behavior separate from observed results. Do not invent components,
adoption, releases or accessibility certification. Preserve unknown
owners and unexecuted checks as blanks or explicitly pending.
Hand the specification and source to a colleague and ask them to explain where RN-02 may be used. A NOS reading copy can keep that rule beside the specimen during review. Finish by checking the actual consumer page against the rule; matching the sample's appearance alone does not establish that it hides the right content.
Download the filled system specification · Download the blank documentation scaffold