Contribute to the design system

This workflow is prepared for owner approval with planned v2.1.0. It supplements product contribution rules and decision recording; it does not override owner authority. Decisions 386/395 prohibit adding delivery automation/protection configuration in this phase and require additive content preservation.

Ownership and review

Role	Accountability
Design-system owner: Shaan Shoukath / Shaan-Shoukath	Approves shared contracts, exceptions, maturity, release scope and publication; owner-only commit/merge authority stays as recorded
Proposing product maintainer	Supplies problem/evidence, implementation, consumer compatibility and migration owner
Design reviewer assigned by owner	Checks task fit, brand/tokens, anatomy, responsive states and content
Engineering reviewer assigned by owner	Checks API/controlled state, dependencies, performance, platform behaviour and adoption
Accessibility reviewer assigned by owner	Checks criterion coverage and actual keyboard/AT/zoom/settings evidence
Consuming maintainer	Verifies the change in at least one independent consumer context and records regressions

These are review roles, not a claim that a new staffed team, CODEOWNERS file or SLA exists. The owner can fill multiple roles for a small change; record that limitation and seek an independent consumer check before declaring broad stability.

Request or contribute

Open a design-system issue or a PR through the existing repository process. If issue creation/access is unavailable, give the same proposal to the design-system owner through the team’s existing channel; no new email address or support service is invented. Products must not fork tokens/components silently when a shared solution is plausible. No tool in this batch sends a message or opens an issue.

Include: product and pinned kit/app version; user task and affected people; screenshot/minimal reproduction in both themes where relevant; existing component/pattern search; why composition fails; frequency/reuse evidence; platform/locale/permission conditions; accessibility barriers; proposed API/token/state change; consuming owners and migration impact. Do not include secrets or private member data in examples.

Proposal → review → build → document → release

Propose: name the task and exclusion cases. Search the component index and P/L patterns. Prefer composition over a new variant with a conflicting purpose. New shared components need evidence in two product contexts, or an explicit owner-approved single-product rationale with an experimental status.
Review: agree ownership, design/API/state/token contract, native versus reference availability and success criteria before broad adoption. Check the latest ledger/public decision. A mismatch between code and rule is an issue to resolve explicitly, not permission to replace the rule silently.
Build: isolate reusable behaviour from product APIs; define controlled values, fetched state, events and dependencies. Preserve compatibility names/paths and existing tests. Supply a self-contained default and a static accessible fallback. Real app copies with missing modules must be labelled reference-only.
Document: use the audit’s 12-part template: support strip; use/exclusions; runnable example/full code; numbered anatomy; variants; every applicable state and reasoned N/A; measurements/tokens; keyboard/a11y; content; do/don’t; API/dependencies/limitations; related/maintenance. Retain every P/S/L/B/C identifier and exact source backlink. New pattern pages name the task and components they compose.
Verify: record actual results against the checklist below, independent consumer evidence and any remaining gap. Re-test affected behaviour after changes. A passing build or automated accessibility scan alone does not prove usability or WCAG conformance.
Release: owner chooses semver, updates maturity/manifest and dated changelog, publishes migration/deprecation details and pins the reviewed immutable release. Integration owner wires routes/sidebar and proves zero content loss. This batch changes no existing site wiring, CI/CD, CODEOWNERS or protection.

Maturity

Level	Entry/exit bar and support
Proposed	Problem/reuse evidence and an accountable owner; no supported implementation promise
Experimental	Opt-in coded/spec prototype, pinned version, known limitations; APIs can change with explicit notice
Candidate	Full 12-part contract and platform-specific evidence; ready for independent consumer validation
Stable	Owner approval, independent consumer use, complete applicable state/a11y evidence and documented support window; platform scope explicit
Deprecated	Stable replacement and migration, notice date/version, removal-not-before date/version and owner
Retired	Removed from current supported API only through the major/versioned process; historical docs/assets remain accessible

Documented reference is an implementation availability label, not a lifecycle claim of stable code. The new component pages use it because source evidence/portable examples exist but no distributable multi-platform package is asserted. An Android colour export does not make a web component stable on Android.

Quality bar

Site checks to run before a release (added 13 November 2026, v2.1.1)

Build the site first (cd site && npm run build: it runs the link check, the publication and integration checks and scripts/check-encoding.mjs). Then, from the repository root, with Microsoft Edge installed (EDGE_PATH overrides it):

Check	What it proves
`node scripts/check-box-grounds.mjs`	Every non-mono logo mark on every page shows exactly one artwork, the right one for its surface (colour on light, black-and-white on dark), in both page themes and through every demo theme switch.
`node scripts/check-site-qa.mjs`	Every page and standalone demo at 390, 768, 1280 and 1680 in light and dark: fixed surfaces identical in both page themes, text contrast 4.5:1 (3:1 large), icon contrast 3:1, focus indicators visible and 3:1, no sideways page scroll, keyboard-reachable scroll regions, images with alt and no upscaling or squashing, 24 px targets, accessible names, unique ids, one main and h1, no skipped heading levels, radio groups and tab lists with one tab stop and arrow keys, nothing looping under reduced motion. `--only <part of a path>` narrows it (separate several with a vertical bar); findings and screenshots go to `site/verification/qa/`.
`node scripts/check-encoding.mjs`	No character lost to a non-UTF-8 write (dashes, ×, ·, curly quotes shown as `?`).
`node scripts/check-box-frames.mjs`	The box-open frames against the logo masters.
`node scripts/check-motion-flow.mjs --browser --require-browser`	Motion tokens, choreography and the browser scenarios.
`node site/scripts/check-integration-browser.mjs`	Runnable demos and their geometry.
`node scripts/check-previews.mjs`, `node scripts/check-css-layer-imports.mjs`, `node scripts/tokens/validate.mjs`, `node site/scripts/check-tokens.mjs`	Previews are current, no component opens a CSS layer, tokens and exports agree.

Every check must report zero failures. The QA sweep takes about half an hour.

Exceptions and mismatches

Record the rule/criterion, user/task reason, affected product/version/platform, alternatives considered, impact, compensating behaviour, accountable owner and a review expiry within 90 days or the next product release, whichever comes first. The owner approves the scoped design exception; it is not a blanket WCAG waiver or a new default. Re-review before expiry, migrate to the shared contract when possible and keep the historical decision.

When sources disagree, use the latest applicable ledger/docs decision and add a dated note beside the old statement through its owning batch. Never delete or reword the original. File a regression with exact pinned version and reproduction if the implementation violates the contract. Changes to a shared rule need the same proposal/review path; local forks do not settle shared policy.