Skip to main content

Component contribution & versioning

How a squad extends the design system without forking it. At agent speed the cheapest move is always a bespoke one-off component — so the governed path has to be cheap too, or squads will route around it and the system fragments in a sprint. This workflow is that path: evidence in, reviewed and tokenised component out, released under semver so every product upgrades deliberately.

The workflow​

  1. Propose with evidence — an issue against the design-system repo naming the pattern gap, linking the screen spec(s) that need it, and stating why no existing component or variant covers it. No evidence, no build — the system grows from real screens, not speculation.
  2. Build with a11y criteria attached — acceptance criteria written before build, including the component-level accessibility behaviour: focus order, keyboard operability, labels/ARIA per the WAI-ARIA APG, contrast (accessibility standard). Agents build against these criteria like any other ACs.
  3. Specialist review — the design specialist (shared specialists) reviews pattern fit, naming, API shape and the accessibility evidence; engineering reviews the component contract. This is the human judgement step — everything mechanical is already automated.
  4. Tokenise — all styling resolves to DTCG tokens; the design-quality toolchain proves there is no raw hex/px before merge.
  5. Document — usage, variants, and when not to use it land in the library docs and as a new row in the design context pack, in the same PR (docs move with the build). An undocumented component is invisible to agents, which means it may as well not exist.
  6. Semver release — patch for fixes, minor for new variants/components, major for breaking changes with migration notes. Products pin a version and upgrade deliberately — a design-system release must never restyle a product by surprise.

The rules​

  • No forks, no local copies — lint flags unknown components at the merge gate. A squad that needs something the system lacks raises a proposal; it does not paste-and-modify.
  • Variant before component — extending an existing component is always preferred over adding a new one; the specialist review enforces this.
  • Deprecation has an expiry — a deprecated component gets a replacement, a migration note and a removal date; it does not linger for ever.
  • Fast lane for small changes — a token value tweak or a new variant of an existing component follows the same six steps at proportionate depth (same gate, less evidence — consistent with scaled gates).
Pending

Repo location, release tooling and the review SLA for proposals depend on the design-tooling ADR and on which design specialist capacity is ring-fenced — both are human decisions still open. The workflow above holds regardless.

Standards referenced: Semantic Versioning 2.0.0, WAI-ARIA APG, WCAG 2.2 AA.