In a design system, what sections belong in a shared component's spec, and what failure does each section prevent?

## What a spec is for A **component spec** is the document that defines a shared component precisely enough that a designer, a web engineer and a native mobile engineer build the same thing without meeting. It is not the usage page that tells product teams when to pick the component, and it is not the release checklist that decides whether it can ship; it is the **contract** those two rely on. The test of a good spec is simple: hand it to two engineers on two platforms, and compare what they build. Every difference is a missing sentence. ## The sections, and the failure each prevents | Section | What it records | Failure it prevents | |---|---|---| | Anatomy | every named part, required or optional | teams naming parts differently, parts dropped on one platform | | Variants | options chosen when placing the component: size, emphasis, layout | ad hoc variants invented per product | | States | runtime conditions: rest, hover, focus, pressed, selected, disabled, loading, error | the unhappy states nobody designed | | Behaviour | interaction, keyboard, responsive rules, overflow, motion | engineers inventing behaviour under deadline | | Content rules | label length, casing, truncation, translation expansion, empty values | layouts breaking on real copy | | Spacing and sizing redlines | internal padding, gaps, sizes, as token references | drift between platforms and modes | | Accessibility notes | role or pattern, accessible name source, keyboard, focus, contrast, target size | inaccessible builds discovered at audit | ## States deserve a matrix States are where specs are thinnest. A spec that shows only the default mockup leaves the most error-prone looks to improvisation. The rigorous form is a **matrix** of variants against states, with impossible combinations marked (a disabled control has no hover look) and combinable ones shown (selected and focused together). ## Redlines in tokens, not pixels A redline that says the gap is 12 pixels is true in one theme, one density and one platform. A redline that references the spacing token for that role stays true when a density mode tightens spacing, when a platform converts units, and when the scale is retuned. Many specs show both, the token name as the source of truth and the resolved number for convenience. ## Content rules and accessibility notes - **Content rules** cover what real text does: the longest expected label, what truncates and what wraps, how a value reads when empty, and how much room translations need. - **Accessibility notes** name the WAI-ARIA role or Authoring Practices pattern the component follows, where its **accessible name** comes from, its keyboard and focus contract, which parts need WCAG 2.2 contrast checks, and whether it is a pointer target subject to target-size rules. - Both are written **with** the visual design, not appended after engineering starts; retrofitting them is where most rework comes from. ## Around the sections 1. **Purpose and scope**: one paragraph on what problem the component solves and what it deliberately does not. 2. **Status**: whether it is a draft, in review or matched to a release. 3. **Open questions**: decisions not yet made, so nobody mistakes silence for a decision. 4. **Changelog**: what changed and when, so consumers can tell which version they built against. ## A billing portal example In a utility company's billing portal, a shared usage meter shows electricity used against a monthly budget. Its spec names the parts (label, track, fill, budget marker, value text), the variants (standard and compact), the states (normal, near budget, over budget, loading, no data), the behaviour when usage exceeds the budget, the content rule for units and rounding, the redlines as token references, and the accessibility notes: the Authoring Practices meter pattern, a visible label as its name and value text that reads as kilowatt-hours, not only a percentage. Two platform teams can build the meter from that page alone.