---
name: "standard-design-system"
type: standard
license: CC BY-NC-SA 4.0
description: The quality bar a design system must clear — token architecture, naming and three-way name alignment, component hierarchy, binding discipline, coverage, documentation, accessibility (WCAG 2.2 AA, stated as run checks), interaction states and motion, and versioning/change discipline — plus the component config record (component.config/v1), the single per-part source of truth Figma and code are both built from. Read before creating, extending, or assessing any venture's or client's design system (skill-brand-system, skill-design-tokens) so quality is judged the same way every run and an existing system can be scored rather than merely used. Sits beside convention-storybook (the code-side instance shape and the three build modes) and convention-figma (the Figma-side file organisation and structural bar). Surfaced by the 2026-07-10 Pixel capture; naming and accessibility added 2026-08-10 (APP-615); binding discipline and the component config 2026-09-04 (APP-804); grown as it is reused.
---

# Design-system standard

What a good design system must contain, stated as a bar the work can pass or fail. This is a *standard*, not a convention: each requirement below is derived, and a system can be scored against it. Owned by Pixel; read by `skill-brand-system` and `skill-design-tokens` before creating or extending any system, and by the read mode in `skill-brand-system` when scoring an existing one. `convention-storybook` holds the code-side instance shape this standard's outputs land in; Sonar's Design System audit (`convention-audit`) is the strategy-level view — this is the craft-level bar beneath it. `convention-figma` holds the Figma-side counterpart — how a design-system file is organised and the structural bar a Figma build is reviewed against. Which side is the reference at any moment — code, the design, or Figma at a refinement pass — is the scope's declared build mode (`convention-storybook`, *Three modes*); this bar holds in every mode.

## The bar — what a complete system contains

* **Token architecture.** Tokens are layered — primitive (raw values) → semantic (purpose-named: `surface`, `text-muted`) → component (scoped where needed) — with a consistent naming scheme stated once and followed everywhere. Theming (dark mode, per-venture variants) is expressed as alternate values on the same semantic tokens, never as a parallel token set. **The rule binds a single-file artefact as much as a system with a library behind it** — one HTML file that ships a hand-rolled set alongside a component library's own (a bespoke `--ink` / `--line` / `--surface` trio beside shadcn's `--sh-*`) carries two parallel sets by construction, and the failure surfaces as a dark toggle that re-values one and leaves the other: half the surface flips, half does not, and neither set is wrong on its own terms. Where an artefact adopts a library's tokens its semantic layer *is* that library's; where it adopts none it mints one set and themes by re-valuing it. Never both. A flat bag of hex values fails this bar.
* **Layout and grid.** The system states its grid as a named part of itself — column count, column and gutter measures, the page maximum, the breakpoint set, and which spacing tokens the grid consumes — rather than leaving each screen to re-derive it. The breakpoint set is stated here once and is the datum the component config's **responsive** section and *Typography*'s descend-at-every-breakpoint check are read against; a system that specifies responsive behaviour per role family while never naming its breakpoints has nothing to check them against. A grid may be inherited whole from the component library or package a venture builds on, and an inherited grid clears this bar only once it is **recorded as the system's own, with its source named and its measures taken from the package rather than from the built screens**, so the next build reads the grid from the system instead of reverse-engineering it. A system whose grid lives only in an external dependency, or only in the shipped layouts, fails. Slide decks do not read this bar: `convention-deck` fixes its own grid and type scale for the slide canvas. (APP-2326. The filing note cites a1-advisory's inherited grid from Vlak as the worked instance; its stated measures do not reconcile arithmetically in the note and are deliberately not carried into this bar — confirm them from the package before any figure is canonised here.)
* **Naming.** One name identifies a part across every surface it appears on — the Figma component name, the Storybook title path, and the code path resolve to the same string — so the design↔code bridge is a lookup rather than a translation. The name states what the part is and where it sits; the layer is carried by the path, not restated as a prefix. A system where the same row is `WorkListRow` in code, `Work / Row` in Figma and `Sections/Work List` in Storybook fails this bar even though each surface is internally consistent.
* **Component hierarchy.** The set is organised in layers — tokens → assets → components → sections → templates (the same hierarchy `convention-storybook` renders) — with each component built from the layer beneath it, not from raw values. A component carrying hardcoded values that bypass the tokens fails. (An illustrative mark is the exception — *The asset record*.)
* **Binding discipline.** Three checkable rules the hierarchy bar implies, stated because each was failed in one shipped part (a1.meirionpritchard.ds, modifier-cell, 2026-08-11 — APP-804). (a) **Documentation names the file's real tokens** — a docs page or config that cites a token cites one that exists in the system, by its real name, never an invented placeholder. (b) **Height derives inside-out** — a row's or cell's height comes from its content plus its padding tokens, never from a fixed-height override; a fixed height that must be kept in step with the padding is two sources of truth. (c) **A part binds existing semantic tokens** — it reaches for the semantic layer the system already has rather than minting a token per part; a new semantic token is added only where no existing one carries the meaning, and is recorded as a system change (*Versioning*). A part shipped with its values un-bound to any token fails all three. Illustrative marks are the one class exempt from this rule and from the hierarchy bar's token-binding clause (*The asset record*, and `convention-figma`, *The structural bar*).
* **Coverage.** The system covers what the venture actually ships: every recurring UI element has a systemised part, and one-off exceptions are named as exceptions. Coverage is stated (what is in, what is deliberately out) rather than implied. A system that documents ten components while the product uses forty fails.
* **Documentation.** Every part carries its usage: when to use it, its props/variants/states, and its don'ts — readable by a human and consumable by a machine (the dual-readable rule in `convention-storybook`). An undocumented part is inventory, not system.
* **Accessibility.** Every part meets **WCAG 2.2 AA**, checked rather than asserted, and carries its accessibility contract alongside its visual states — keyboard model, focus behaviour, accessible name, semantics. A contract that names states but not focus, contrast, motion or semantics is half a contract.
* **Versioning and change discipline.** Changes to the system are deliberate: proposed, recorded (what changed and why), and propagated — never silently restyled in place. Where the system lives in code, the token source is single and changes flow from it (see `skill-design-tokens`); where it lives in Figma, the library is published and consumers update from it.

## Default UI kit — product and console surfaces

**The house default is shadcn/ui as the base, with copy-and-paste Tremor for charts.** Stated here so the next product or console build adopts it rather than re-deriving it in session — which is exactly what happened on the a1.Firmup console rebuild, where the answer was reached in-session and recorded only on the epic (A1-377, 2026-09-03).

* **Base: shadcn/ui.** MIT, **no licence to buy**, React 19 + Tailwind v4 per its own docs. Copied into the repo, not installed.
* **Charts and dashboard idiom: Tremor, copied and pasted** (`tremorlabs/tremor`, Apache 2.0, Radix + Recharts, now under Vercel) **where the dashboard idiom earns it** — not as a blanket second kit.
* **Recharts sits under both**, so the chart layer is one dependency rather than two.

**Why the copy-and-paste model is the rule and not an incidental.** The code lives in the repo, so there is **no package to fall behind React on**; theming goes through CSS variables per `skill-design-tokens`; and a part can be edited in place to bind the system's own semantic tokens, which *Binding discipline* requires and a black-box package forbids. That is the model that fits how Forge works, and it is the reason the default is stated as a copy-and-paste pair rather than as two dependencies.

**Two anti-patterns, recorded because both were live confusions and both cost time.**

* **The Tremor *npm package* is a different thing, and it is the one that stalled.** `tremor-npm` has had no React 19 support since issue #1072 was opened in May 2024, which is why the earlier console build considered it and dropped it. Copying Tremor components in is not the same decision and is not blocked by that issue. Do not read "Tremor" in this section as the package.
* **The paid "shadcn" sites are not a licence for the kit.** Shadcn Studio, shadcnuikit and shadcndesign are **third-party template shops**. So "should we buy a licence for shadcn?" answers **no**: the kit is MIT and there is nothing to buy.

**Tremor Blocks & Templates (paid) is not held as a layout reference**, and is not until a second console build actually wants it. One build is not a pattern, and a paid reference bought for one surface is a cost with no second consumer.

**Reconciles with *The bar*'s token-architecture rule, and the reconciliation is load-bearing.** That bullet already names shadcn's `--sh-*` set as its worked example of the failure it forbids: an artefact carrying a bespoke semantic set *beside* a library's own, where a dark toggle re-values one and leaves the other. Making shadcn/ui the default makes that the **common case rather than an edge one**, so state the consequence explicitly: **adopting shadcn/ui means the system's semantic token layer *is* shadcn's, and no parallel bespoke set is minted beside it.** Extend it rather than duplicate it — a new semantic token is added only where none of shadcn's carries the meaning, and is recorded as a system change per *Versioning and change discipline*. A build that copies in shadcn/ui and then hand-rolls its own `--ink` / `--line` / `--surface` trio has failed the token-architecture bar while following this section's kit recommendation, which is why the two are written to be read together.

Owner artefact: Pixel. Provenance: Owner ruling 2026-10-20 (reported via Aide, APP-2279 form) — "shadcn/ui is the house base UI kit, with copy-and-paste Tremor for charts, as the default in `standard-design-system`" — on the question raised 2026-09-04 and answered after **46 days** (observed). Filed from the a1.Firmup console rebuild A1-377, 2026-09-03; sources checked that date per the note body; APP-1096.

## Token reuse — by meaning, never by value

*Binding discipline* (c) says a part binds an existing semantic token rather than minting its own. Three rules extend it to the case it does not cover: the token that already carries the meaning is there, and nobody is using it. Each was failed on one pass (a1.meirionpritchard.ds nav tokens, 2026-09-08 — APP-1181).

* **Never delete an orphan as cleanup.** A token whose components have moved on is re-valued into the current set — re-valued to what the work needs, renamed where the meaning has narrowed or split, and re-pointed at — or left in place with a recorded reason. Delete-then-create looks identical in the file and is not: the variable's identity goes with it, so every existing binding breaks and a component that referenced the old token falls silently back to a raw value instead of following the new one. Re-valuing keeps both the identity and the record that the value was once considered, and reaches the same end state.
* **Match on meaning, never on value.** The test is whether a token *means* the thing being bound to it, not whether its current value happens to match. Binding a nav to `space/hero-y` because both hold 20 couples two unrelated parts, and a later change to the hero bar's padding then moves the nav silently. The right reuse was `space/nav-y` — an orphaned nav token, re-valued for nav work.
* **Never collapse two semantic tokens because they resolve to the same primitive.** Two semantic tokens holding one primitive is the tier working as intended, not duplication: two parts can each carry their own semantic token even where both currently resolve to the same primitive, so one part's token can be re-pointed later without dragging the other with it. An audit that deduplicates by value has broken the system rather than tidied it.

The last rule binds the audit as much as the build. *Find the duplicate values* is the obvious way to write a token sweep and it is precisely wrong here: a sweep reports same-primitive pairs as observations, never as findings, and an orphan as a candidate for re-valuing, never for deletion.

## Typography — the ramp as a checkable bar

`skill-brand-system` step 2 already sends a venture's **type scale** here to be scored — "palette, type scale, logo usage, spacing … — to the bar in `standard-design-system`" — and until now this standard stated no bar for it, so a ramp could be built, overridden and shipped with nothing to check it against. These are the properties a ramp is scored on, each **pass / partial / fail** like every other bar above. (Surfaced by one audit — mbn.type-ramp-review.pass-1 on the Meirion storefront, 2026-10-03 — whose findings are **one** gap and not six: the bar was missing, not six bars. APP-1999, folding APP-2000, APP-2002 and APP-2003.)

* **A stated ratio, and ordinality that is checked.** The steps between roles come from **one stated ratio** the system names once — a modular scale (1.2, 1.25, 1.333) or an explicitly stated bespoke set — never from a value chosen per role. And the numbered heading roles are **mechanically checked to descend: h1 ≥ h2 ≥ … ≥ h6 at every breakpoint**, as *rendered* size, so an override cannot silently invert the hierarchy. This is **not** check 5's "heading levels descend without skipping", which governs the *level sequence in the markup*; this governs the *rendered sizes those levels resolve to*, and the two are independently wrong — a document can have faultless heading levels and an inverted ramp. A ramp with no stated ratio fails; a ramp whose rendered order inverts fails whatever its markup does. (Observed: h1 at 15px rendering smaller than h6 at 16px desktop and the same size as body copy, with no ratio governing 56→50→40 or the cliff to 15→13→11→10→12→15/16 — so nothing could have caught the inversion before an audit caught it by eye.)
* **Tracking is relative, never a fixed px offset.** Letter-spacing is expressed in **em or %**, because tracking reads as a proportion of size: one flat px value is imperceptible at the top of a scale and loose at the bottom — a +0.6px offset is ≈0.8% of a 72px display role and ≈4% of a 15px body role, from the same declaration. The system states **family-level defaults** — zero-to-negative at display sizes, near-zero through body and the numbered headings, positive only on small-caps and label-style roles (badges, captions, buttons) where it is doing real legibility work — and a role departing from its family's default carries a reason. A ramp carrying one fixed-px value across the whole scale fails. (APP-2000.)
* **A derived type value is recomputed when the value it derives from changes.** This is *Binding discipline* (b) — "height derives inside-out … a fixed height that must be kept in step with the padding is two sources of truth" — reaching the type ramp: a **line-height fixed in px that must be kept in step with a font-size is the same two sources of truth**. So whenever a font-size override is applied to an existing role, its line-height is **recomputed as a deliberate ratio of the new size**, never left at the value the old size produced. The tell is a run of oddly precise, non-round unitless ratios across adjacent roles (1.267 / 1.385 / 1.455 / 1.6 on h1–h4), which is what a stale fixed-px line-height divided by a shrunken font-size looks like. Treat that pattern as a prompt to read the declaration, not as a finding on its own: on the one observed instance it was scored **assumed** — inferred from the pattern and the baseline's own provenance note, not confirmed from raw CSS — and the rule stands on (b) rather than on that instance. (APP-2002.)
* **Responsive behaviour is stated per role family, not emergent.** The system states, **for each role family, whether it scales by breakpoint or stays fixed, and why** — expressed through the semantic modes the component config's **responsive** section already requires, never as a per-role device variant. An unstated pattern is not a decision, and the tell that it never was one is an inconsistency *inside* a single family. (Observed: h1–h4, `.button`, `.badge`, `.caption-with-letter-spacing`, `.form__label` and the table-cell role fixed across breakpoints while the display roles, h5, h6, body, price and `.caption` scale — h1–h4 fixed and h5–h6 scaling inside the same heading family. APP-2003.)
* **An interactive or UI text role is measured at its box, not at its font-size.** A button, form control or badge is checked against *Accessibility* check 3 (WCAG 2.2, 2.5.8) with its **padding and box dimensions read alongside its font-size in the same pass**, so target size is answerable from the ramp read rather than deferred to a component pass that may never happen. Where such a role renders **below the system's own body size**, that is recorded as a named exception carrying a reason (*Where a bar cannot be met*), never left as an unremarked value. (Observed: `.button` at 10/10px. **A stated minimum px floor for these roles is deliberately not set here** — a floor is a new bar level that neither WCAG nor anything else in this standard derives, so it is an Owner call, open on APP-2001. Until it lands, this clause is the check and the named exception is the remedy.)

**Scoring.** Score the ramp **per property**, as *Accessibility* is scored per check, so a ramp passing ordinality and failing tracking reads as two findings rather than one blurred verdict. Where the only available surface is a computed-styles baseline, the ratio and the controlling unit may not be readable from it at all — tag those **unknown**, never **fail** (*Scoring an existing system*).

*Provenance.* The storefront figures quoted above are mbn.type-ramp-review.pass-1's own readings and are **unverified** from the refine surface, which can read no repo and made no live-page read; that flag covers those quoted px values only. The five rules are derived from this standard's own *Binding discipline* (b), the component config's **responsive** section, *Accessibility* checks 3 and 5, and WCAG — none of which turns on those readings.

## The component config — one record per part (`component.config/v1`)

Every part carries one config record, and it is the **single source of truth Figma and code are both built from** — not a document written after the fact from either. The schema, `component.config/v1`, has ten sections; a record that omits one names the gap rather than leaving it implicit. Seven describe the part; three — **binding**, **measurement** and **provenance** — exist so that a code build can reach parity from the record alone and a reviewer can check parity by measuring rather than by reading.

| Section | What it holds |
| -- | -- |
| **meta** | The part's one name (the three-way-aligned string, *Naming*), its layer (component, section, template), its status, and the family it belongs to. |
| **tokens** | The primitive → semantic → component chain the part consumes, by real token name; any component-scoped token it introduces, and why. |
| **anatomy** | The layer tree — and the same tree is the Figma layer structure and the code's slot structure. One tree, three surfaces. |
| **api** | Variants, props and states with their allowed values and defaults; what is a variant in Figma is a prop in code, under the same name. |
| **responsive** | How the part behaves across breakpoints, expressed through the system's semantic modes rather than a per-part device variant. |
| **a11y** | The accessibility contract (*Accessibility*, check 6): role, accessible name, keyboard model, focus behaviour, state announcements. |
| **docs** | The dual-readable usage — when to use, when not to, don'ts — that renders as the family's Figma doc frame and the Storybook autodocs alike. |
| **binding** | Per token row and per layer, the **code** side beside the Figma side: the code token path or CSS variable, and a flag wherever code uses a literal where Figma binds a variable. |
| **measurement** | What each number is measured on — Figma frame, CSS border-box, rule-to-rule pitch — the expected value per mode, which viewport width selects which mode, and, for type, the line box and trim mechanism per surface. |
| **provenance** | The Figma node ids, the file version and the code commit the record was last reconciled against. |

**Every section states both surfaces, and a divergence is written down rather than discovered.** The seven sections above were written from the Figma side and read as though code follows by construction. Where it does not, the record is not merely incomplete — it is wrong in the one direction a builder will act on, stating a number that is true in Figma and false if applied to code. So each existing section carries the code side explicitly. **anatomy** names, per layer, the DOM element or class, the slot-visibility rule, and the sizing shape: fill or fixed, minimum width, wrap or truncate. **api** names, per Figma property, the code prop and the value map, with "no code equivalent" stated rather than left blank, and, per state, how code implements it and the story that proves it (`convention-storybook`). **responsive** names, per mode axis, what the mode means in Figma, what it means in code, and what the part does under it. And wherever the two surfaces genuinely differ — a deliberate mechanism change, a value bound on one side and literal on the other, a mode that touches one surface and not the other — the record **states the divergence and the reason for it**, because *Naming*'s rule that a Figma variant is a code prop under the same name is the default, and an exception nobody wrote down reads as parity. The test for the three added sections is the same as for the seven: a record that omits one names the gap. (Worked case: A1-604, the cell, parity pass 2026-10-05 — Figma values read from the file, Storybook rendered and measured at 1280, 1024, 640 and 600 wide. Height, padding, gap, border, selector, handle and label size all agreed; every difference was something the record did not state, so each had to be found by reading CSS and measuring. The record lists label line height 30/22 where code sets it to the selector size, 20/16, as a deliberate mechanism change, so a build from the record alone produces a 60px row rather than 50. Heights are given as 50 and 38 — Figma frame heights with a centre-aligned 2px stroke — against a browser border-box of 52 and 40, and the record does not say which is measured. Token names differ per surface (`space/cell-y` against `--cell-pad-y`, `theme/content` against `--ink`, `type/cell-size` against `--fs-nav`), with two code values literal where Figma binds a variable. Five Figma properties map to differently named code props or to none. And dark mode means two things: a Figma theme mode that flips the cell, against code where `body.dark` never touches it. The trim half of **measurement** has a second, independent instance on the Figma side — a cap-height-trimmed style cropped by a frame's Clip content, APP-2069, folded in `convention-figma` and carried here as evidence. Premises unverified — no repo access from this refine surface: the Storybook measurements at `origin/main` 5b0c2b8, the Figma file and its node values, the token names and every px figure above are the filing leg's report, and whether Figma's text-box trim explains the 18px label box at 25px size was not read directly; that flag covers those figures only, not the rule, which rests on this section's own single-source-of-truth statement and on the Owner's 2026-10-05 ask. APP-2070.)

**A part owns its surface, or states that it depends on its host — and the anatomy row carries which.** The code side above already names, per layer, the DOM element or class, the slot-visibility rule and the sizing shape: fill or fixed, minimum width, wrap or truncate. It does not name who paints the layer's ground, so a part with no fill of its own records nothing on the point and reads as complete. That part is not theme-neutral — it inherits whatever its host paints — and *The bar*'s token-architecture rule cannot express it, because theming is alternate values on the same semantic tokens and a layer that binds no surface token has no value to alternate. So **anatomy** states, per layer, whether the layer **owns its surface fill**, naming the semantic token it binds, or **depends on its host**, naming the hosts it is specified against and what each is expected to paint; "no fill" recorded on its own is the gap named, not the answer. And a host-dependent layer is checked in a host: the per-part check renders it inside a representative host, in each theme mode, because a part shown on its own is shown against the one ground on which the dependency cannot fail. The ticket-side form of the same bar is `convention-ticket`'s gate 1 for a design-system component variant, and the two are written to be read together. (Worked case: a component variant labelled `surface=panel`, carrying no fill of its own, renders white-on-white in dark mode once placed inside a block, while the per-component check showed it only on its own, where the dependency is invisible. The variant, its label, the dark-mode rendering and the per-component check's framing are **reported** by the operator-a1 session; no Figma file and no repo is readable from this refine surface, and that flag covers those particulars only — not the rule, which rests on this section's single-source-of-truth statement and on *The bar*'s token-architecture rule. APP-2576.)

The record is written when a part is added or restructured, and the Figma build and the code build are each checked against it rather than against each other. Worked examples exist for `alert` and `modifier-cell` (a1.meirionpritchard.ds, 2026-08-11). The working form — YAML, one file per part, kept beside the part in the repo where the system lives in code, and mirrored on the family's `doc/config` frame in Figma (`convention-figma`) — is not yet scored; the presence and completeness of the record is. `skill-design-tokens` maintains the records; `skill-brand-system` read mode scores whether they exist.

## The asset record — one record per mark

An asset (an icon, a mark, a spot) is a part with no behaviour, so most of `component.config/v1` has nothing to state for it (api, responsive, binding), and what matters for a mark is not in that record. An asset carries an **asset record** instead, mirrored on the assets page's `doc/config` frame (`convention-figma`, *File organisation*). It states:

* **source** — the exported SVG as the source of truth, and where it lives; "not yet exported" is written rather than left blank.
* **size and stroke** — recorded as values (the main's size, stroke weight, corner radius), each marked bound to a variable or exempt.
* **exemption** — for an illustrative mark, the token-binding exemption (`convention-figma`, *The structural bar*), written on the record. An unbound value with no exemption stated is a defect; one with it is a finding of none.
* **motion** — the animation, where the mark has one, with its reduced-motion behaviour (*Accessibility*, check 4).
* **accessibility** — decorative or labelled, and the accessible name where labelled.
* **usage** — where each mark is used.

A record that omits a field names the gap, as the component record does, and presence and completeness are what is scored. **Illustrative marks are exempt from token binding** (Owner ruling, Aled, 2026-10-09 — APP-2204): bespoke artwork, its values are optical tuning, and the check is that it renders identically to its exported SVG. UI-structural icons (`assets/icon/*`: close, drag-handle, selector) are not marks in this sense. They carry an asset record too, and bind tokens. The value-level question — a register of deliberate literals and derived values across the system — is not settled here and is carried by the open token-section and token-convention proposals (APP-2087, APP-2088). (Owner, Aled, 2026-10-09: the documentation for the assets pages "might need to be different from the component pages as they have different requirements" — APP-2205. The six fields are the filing leg's session observation, adopted here as the drain's wording, and they are not a named schema version. Premise unverified: that the nav marks are consumed in code as exported SVGs and are an animated set rests on the titles of A1-124 and A1-204; no repo or Figma file was read from the refine surface. That flag covers those two points only.)

## Naming — the bar, and the part that is only a convention

Two different things travel under "naming", and only one of them is a standard. Keeping them apart is what stops an arbitrary lexical choice being scored as a quality failure.

**The bar (a standard — one choice is better).** Three-way resolvability, as stated above: one string, three surfaces, derivable without a mapping table. It is a standard because misalignment has a cost that is not a matter of preference — every bind between Figma, Storybook and code becomes a translation, and translation is where the bridge silently rots. It is testable: take ten parts at random and check that the Figma name, the Storybook title path and the code path are the same string. Any part that needs a lookup table fails.

Two further bar-level properties follow from it:

* **The scheme is stated once and covers tokens and components alike** — one scheme per system, written down in the system's own documentation, not inferred from the existing entries.
* **The system's name wins over a build's name.** Where a build ships a part under a different name, the system's name is authoritative and the rename is scoped into the build's work — never absorbed as a permanent alias, which reintroduces the mapping table by another route.

**Only a convention (arbitrary-but-shared).** The lexical form itself — slash- or dot-delimited, lowercase or PascalCase, singular or plural nouns — is a choice where two sensible people could each decide differently and only agreement matters. By the test in `core-operating-model` that makes it a convention, not a standard, so it is **not scored** here. It is written here because the estate reads design-system naming from this artefact and from nowhere else; when the form hardens it belongs in a convention, and moving it there is a later, deliberate step rather than a reason to leave it homeless now.

**The current scheme, held as a trial instance.** The Meirion Work-section blueprint fixed: slash paths, lowercase, singular nouns, the layer carried by the path (`components/project-row`, `sections/work-list`), no layer prefixes. That is the working scheme for that trial and not yet general canon — the blueprint-first model it belongs to is itself under trial, with the verdict due on the A1-231 epic (APP-613). Score a system against the alignment bar; do not score it against these lexical choices until the trial returns a verdict.

## Accessibility — the bar, stated as checks

The named level is **WCAG 2.2 AA**, applied to every part of the system and to every theme it ships: light, dark and per-venture variants are each a separate pass, because a pair that passes on one ground can fail on another. AA is the bar, not the aspiration — a part below it is not finished. `standard-prioritisation` already treats an accessibility failure as **Critical**; this section is the definition that severity has been presupposing.

Seven checks. Each is run and recorded, never asserted.

1. **Contrast, checked at the token pair.** Body text and text-like elements at least 4.5:1 against their ground; large text (24px and above, or 18.66px and above when bold) at least 3:1; non-text essentials — component boundaries, form-field borders, focus indicators, and icons or chart marks that carry meaning — at least 3:1 against what sits next to them. Check the **semantic token pairs** (`text-muted` on `surface-raised`, and so on) rather than screenshots: the pair is the unit that recurs, so checking it once covers every component that uses it, and a new component inherits the result.
2. **Focus visibility and order.** Every interactive element is reachable by keyboard, in an order that matches the visual reading order. The focus indicator is visible, holds at least 3:1 against what surrounds it, and is never removed without a replacement. Focus is not trapped except deliberately inside a modal, which returns focus to its trigger on close.
3. **Target size.** Pointer targets are at least 24 × 24 CSS px with enough spacing that neighbours do not overlap (WCAG 2.2, 2.5.8), or an equivalent-size alternative exists on the same surface. 44 × 44 is the preference for a primary touch target, not the bar. **For a text-only target the font-size is not the measurement** — the target is the box, so read padding and box dimensions **alongside** font-size in the same pass rather than inferring one from the other; a type-ramp read that reports sizes without boxes has not checked this criterion and says so (*Typography — the ramp as a checkable bar*). (APP-2004.)
4. **Motion preference.** Every animation, transition, parallax and autoplay honours `prefers-reduced-motion: reduce`, and the reduced branch is a real branch — the motion is removed or replaced with a plain fade — not the same motion with a shorter duration. The branch lives in the motion/token layer so it applies system-wide rather than being re-implemented per component. Name the mechanism and check it actually runs: a reduced-motion claim offered as a rationale with no mechanism behind it is how this check is failed while reading as passed (worked case: APP-726).
5. **Semantic structure.** Native semantics first — a button is a `button`, heading levels descend without skipping, every control has a programmatically associated label, landmarks appear once each, and images carry alt text or are explicitly marked decorative. ARIA is used only where no native element carries the meaning, and never to relabel a native element that is already correct.
6. **The documented contract.** Each part's documentation states its keyboard model (which keys do what), its focus behaviour, its accessible name, and its role and state contract — in the same dual-readable place as its props (`convention-storybook`), so both a human and the machine layer read it.
7. **Text that survives being resized and re-spaced.** Two AA criteria bind the **type ramp** specifically rather than any one component, and neither is answerable from a table of computed values — both are **live tests**, which is why a ramp read reporting only computed px skips them silently and reads as passing. **1.4.4 Resize Text:** text reaches **200%** without loss of content or function, which turns on the **controlling unit in the source** — a computed-px baseline reports `15px` whether the declaration was `15px`, `0.9375rem` or a clamp, and only some of those resize. So read the **declared** unit, not the computed value, and confirm the enlargement in a browser. **1.4.12 Text Spacing:** with line-height forced to **1.5× font-size**, paragraph spacing to **2× font-size**, letter-spacing to **0.12em** and word-spacing to **0.16em**, no content or function is lost — applied as a **DOM override on the running page**, never reasoned from the static values, because what fails here is overflow and clipping and the values do not carry it. Record both as run, naming the unit read and the override applied; a ramp whose criteria were inferred from a computed-styles baseline alone is scored **unknown** on these two, never **pass** (*Scoring an existing system*). (Surfaced by mbn.type-ramp-review.pass-1, 2026-10-03, where both came back unresolvable from the baseline that pass had — APP-2004. That provenance claim is the audit's own and is **unverified** here; the criteria themselves are published spec and the omission was verified by reading all six checks above.)

**How the checks are run.** Automated first: an axe pass over the story set, which Chromatic already runs beside its visual snapshots on a wired repo (`convention-github`). Then a manual keyboard pass per part — tab to it, operate it, leave it. Automation is necessary and not sufficient: it does not see a wrong focus order, a valid-but-wrong heading level, or an accessible name that reads as nonsense. A part is scored on both, and an automated-only pass is scored **partial**.

**Measuring contrast in a running browser — the seven traps, and why they are silent.** Where the contrast check is met by measurement rather than by a token-pair table — a themed console, a hovered state, any pairing that only exists at runtime — the measurement is written against a live page, and the obvious implementation is wrong on a modern token theme in ways that produce specific, plausible, false numbers. The direction of the error is what makes this a rule rather than a tip: each trap is as capable of a false pass as a false failure, and a PR body carries a table of numbers either way, so nothing downstream can tell them apart. Seven traps, all observed, all in the same sixty lines:

1. **Resolve every colour through a canvas, never a regex.** A utility such as `bg-primary/90` compiles to `color-mix(in oklab, var(--color-primary) 90%, transparent)`, and `getComputedStyle` returns that string verbatim; a parser matching `rgb(` / `rgba(` matches nothing, returns "no colour", and silently measures the element *behind* the one under test. Set `ctx.fillStyle` on a 1×1 canvas and read the pixel back — the browser resolves any CSS colour syntax.
2. **Detect a refused parse.** After `ctx.fillStyle = value`, confirm the browser did not fall back to `#000000` on a value it could not read, and report a refusal as an error rather than measuring it. Without that check the failure is the same silent one — a plausible number for a colour nobody resolved.
3. **Start the ground walk at the element itself when the element paints its own background.** Walking up from `parentElement` unconditionally measures a filled button's label against the surface behind the button.
4. **Plant the probe inside the element the tokens are scoped to.** Where a theme scopes its token layer to a container rather than `:root`, a probe appended to `body` reads a different set of values under the same names — and reads them as a legitimate, passing pairing.
5. **Choose the negative control, and prove it fails.** A control is only a control if it is known to fail and observed failing. Two ways it silently does nothing: it draws a token that is not the kind of token you assumed (a surface where you wanted text), or it is injected as a *class* the source scan has never seen, so the class compiles to nothing and the probe inherits the foreground. Write it as an inline token reference, and **assert the control's two theme readings differ** — a control drawn from the theme's own tokens cannot measure the same in both themes, so identical figures mean the probe is reading a fixed ground rather than the theme.
6. **Wait out the transition after a theme switch.** Where the theme is a class on the root element and the surface carries `transition-colors`, a probe that toggles the class itself is not covered by the theme library's transition suppression, and sampling immediately reads mid-interpolation colours. Set the motion duration to zero for the probe, or settle past it before sampling.
7. **Measure a layered indicator from painted pixels, never from computed style.** Where the indicator is built from more than one stroke — an outline plus a box-shadow, a ring plus an offset, stacked inset shadows — `getComputedStyle` reports every layer's colour whether or not it survived compositing, so a check that reads each layer's colour and credits the best contrast among them is true by construction. Two strokes can occupy the same band and the one on top is the only one that reaches the screen; the figure for the covered tone is then real, plausible, and about a colour no viewer will ever see. So sample the ring and its backdrop from `page.screenshot({ clip })` and decode the pixels in the same browser that painted them, and **pin each band's painted pixel to the token it is meant to be** rather than only asserting a ratio: once both tones are ink and paper, the better of the two contrasts clears 4.5:1 against almost any surface, so a ratio alone cannot tell a two-tone ring from a one-tone one. Two corollaries. An offset measured from the border's outer edge and a spread measured from the padding edge can coincide without either declaration looking wrong, so build a two-tone ring from **two strokes of the same kind** — both inset, or both outer — which keeps one reference frame and leaves stacking order as the only thing governing visibility. And an alpha-not-255 guard against anti-aliased edges is inert here: a page screenshot is opaque, so a blended edge returns alpha 255 and only the equality pin catches it.

Where a repo meets this bar on more than one ticket, the measurement is **committed to that repo as a script and run**, not re-implemented per change: a fix to the maths then fixes it for every future run, which re-implementation cannot. (Worked case: `assoc-one/firmup-operator`, 2026-09-08 — six console leaves against one contrast bar, four legs each hand-building the harness, and four separate rounds lost to correcting the instrument before the measurement could be believed. A1-385 reported a hovered button at 1.22:1 dark / 1.14:1 light against a true 4.71 / 6.41; A1-386 round 2 reported a negative control passing at 6.86:1 in both themes; A1-387 reported light-mode muted text at 2.19:1 against a true 5.16:1. Every one of those was the instrument, not the build — APP-1195.)

**Where a bar cannot be met**, record it as a named exception carrying a reason and a ticket. An unmet criterion that is written down is a finding; one that is not is a defect the system will keep reproducing into every part built after it.

**Scope.** This is the design-system half — the parts and the contracts they carry. Accessibility at the product level (whole journeys, content and alt-text authoring, service copy) crosses product design, build, review and content, has no canon home, and is not closed by this section.

## Interaction states and motion — the bar

**Every interactive part states its interaction states, and every system states its motion, as named tokens held in this artefact's own token layers.** The *what* is Owner-ruled: Pixel needs a canon answer for an interaction-state question, and until now there was none — a hover question had no home, so an in-session ruling landed only in a repo's CSS and a project log and was unreadable by the next run. **The how/where — that interaction states and motion belong in `standard-design-system` rather than in `convention-aesthetic` — is a how/where ruling of this refine pass and not the Owner's**, taken because this standard already holds the token-level contract a state or a duration is expressed in (*Token architecture*, *Token reuse — by meaning, never by value*), while `convention-aesthetic` governs taste rather than tokens; record it with that attribution and never as an Owner ruling. The bar has three limbs. (a) **The state set is named and complete per interactive role family** — at minimum rest, **hover**, **focus**, **pressed**, **disabled** and **loading** for every part that takes a pointer or a key, with a role family that genuinely lacks one naming the omission as an omission rather than leaving it unstated. (b) **Each state is expressed as named tokens, never as a one-off value in a component or a stylesheet**, and where a state changes colour the system records the **measured contrast** of the resulting pair beside the token name, read at the semantic pair exactly as *Accessibility* check 1 reads it — a state whose colour is recorded without its measured ratio has not cleared this limb. (c) **Motion is stated as a named set too** — the durations in use, the easing curves, and each **spring** form with its own parameters — with the `prefers-reduced-motion` branch held in that same layer, which is where *Accessibility* check 4 already requires it to live. **And a value that is not a system default is recorded against the project rather than left in the build**: where a venture or client build needs a state or a duration the system does not carry, that value is written into the build's `convention-brand` instance (or the venture's own design-system record) as a named project-specific token, with its source and its measured contrast where colour is involved, and the system default is left unchanged — because a value that exists only in repo CSS or a project log is homeless, and homelessness is the failure this section closes. (Worked case, the filing note's own evidence and therefore **reported**: `APP-2809` arrived as three instances on one root — the note's body plus two `[close-out]` comments, each adding a further homeless ruling — carrying an A1 hover and chip-colour decision whose contrast arithmetic was stated as `#595959` at **7:1** (**reported**) and a panel open/close motion of **0.65s** spring (**reported**), neither of which had a canon home at the time of filing; both are recorded here as the shape such a value takes and not as this system's defaults. Context, and the reason the project-side home is named explicitly: `convention-brand`'s A1 palette was **retracted** in sprint `A1-697` (**reported**), so a state colour parked against a retracted palette has no standing either, and what this limb requires is a named project token carrying its own measured figure rather than a reference to a palette that has been withdrawn.)

## Scoring an existing system

When ingesting a system Pixel did not create (the read mode in `skill-brand-system`), score each bar above **pass / partial / fail**, and tag each finding **known** (observed directly), **assumed** (inferred), or **unknown** (not inspectable from the available surface). Two bars score at a finer grain: **naming** is scored on alignment and on the two properties that follow from it, never on the lexical form; **accessibility** is scored per check, so a system passing contrast and failing focus reads as two findings rather than one blurred verdict. The scored inventory doubles as the craft-level input Sonar's Design System audit consumes — produce it once, let the strategy layer read it.

## Guardrails

* The bar judges the system, not the taste — aesthetic judgement lives in `convention-aesthetic` and the venture's `convention-brand` instance.
* Score what is observable; name what is not (unknown), never fill it.
* Score naming on alignment, not on the lexical scheme — and treat the Meirion scheme as a trial instance until its verdict lands.
* Accessibility is a bar, not a preference, and is not traded against an aesthetic choice: where the two collide, the palette or the treatment moves.
* A failed bar is a finding to raise, not a licence to unilaterally restructure a client's or venture's live system.
