Guideline 06Canonical

Governance and contribution

Ownership, maturity, contribution, release, adoption, exception, and deprecation rules for keeping the system trustworthy.

Owner: Design Systems
Last reviewed: August 2026
Review cadence: Monthly operating review
Source of truth: Repository, package releases, and this portal

Required outcomes

Teams know what is safe to adopt and who decides changes.

Design and code publish as one reviewed release.

Every consumer release moves through a visible, recoverable adoption lifecycle.

Exceptions and deprecations include an owner and an exit path.

Maturity and ownership

Every shared asset has a status, accountable owner, review date, and canonical implementation.

Maturity model

Status	Use	Promise
Draft	Evaluation only	Shape and API may change without migration.
Beta	Opt-in product use	Known gaps are documented; breaking changes include direct outreach.
Stable	Default for production	Semantic versioning, migration guidance, and regression coverage.
Deprecated	Existing use while migrating	Replacement, deadline, and removal version are published.
Retired	Do not use	Removed from active libraries and retained only in history.

Decision rights

Role	Accountability
Design Systems	System coherence, asset model, tokens, docs, final acceptance
Frontend Platform	Public API, semantics, performance, package quality
Product designer	Use case evidence, workflow fit, content and responsive validation
Product engineer	Integration evidence, edge cases, adoption and migration feedback
Accessibility reviewer	Manual behavior and conformance risk

Contribution workflow

New system surface area begins with repeated product need, not a polished component proposal.

From need to release

01
Frame
Owner: Contributor
Problem, affected workflows, evidence from at least two contexts
Exit gateA shared need exists and composition cannot solve it cleanly.
02
Explore
Owner: Design and engineering
API, anatomy, states, tokens, accessibility, content and responsive model
Exit gateThe smallest coherent contract is selected.
03
Build
Owner: Contributor
Code, design asset, docs, tests, examples and migration notes
Exit gateParity and quality checklist passes.
04
Review
Owner: System owners
Design, API, accessibility and visual approval
Exit gateNo unresolved release blocker remains.
05
Adopt
Owner: Product team
Pilot evidence and follow-up issues
Exit gateBeta graduates after real workflow validation.

Proposal evidence

Problem

Two or more concrete product contexts.
Why existing primitives and patterns are insufficient.
User and accessibility consequences.
Expected adoption and maintenance owner.

Solution

Public API and design properties.
Complete state, content, responsive, locale, and theme model.
Token impact and visual rationale.
Testing, rollout, and migration plan.

Release and change management

Documentation, package behavior, design assets, and migration guidance move together.

Change classes

Class	Examples	Requirement
Patch	Bug fix, docs clarification, accessibility correction without API impact	Regression test and changelog entry
Minor	New component, prop, token, recipe, or compatible visual capability	Docs, examples, design asset, adoption note
Major	Removed or renamed API, changed default, token meaning change	Deprecation window, codemod or migration, owner outreach
Emergency	Security or critical accessibility fix	Expedited review plus follow-up documentation and audit

Deprecation contract

Name the replacement

A deprecation without a supported next step is not actionable.

Provide a deadline

Publish the earliest removal version and a review date.

Measure remaining use

Track package references or product inventory before removal.

Keep the old path stable

Do not silently change deprecated behavior during the migration window.

Consumer adoption lifecycle

Consumers opt into update discovery, validate releases in their own environment, approve them manually, and deploy on their own schedule.

Release to production

01
Publish
Owner: Design Systems
Immutable vX.Y.Z tag, GitHub Release, and reviewed notes
Exit gateRelease workflow passes without moving an existing tag.
02
Propose
Owner: Consumer updater
An optional package.json and package-lock.json pull request
Exit gateBoth files resolve the same immutable release tag.
03
Validate
Owner: Consumer CI
Consumer-owned typecheck, lint, tests, policy checks, accessibility checks, and production build
Exit gateApplicable compatibility checks pass; a provider preview does not substitute for them.
04
Approve
Owner: Product owner
Release-note and product-impact review
Exit gateA human merges; automerge stays disabled.
05
Deploy and verify
Owner: Consumer owner
Normal deployment plus an affected-workflow smoke test
Exit gateThe deployed consumer behaves as reviewed.
06
Monitor
Owner: Consumer owner
Optional scheduled freshness signal
Exit gateMonitoring reports staleness without changing the application.

Choose an adoption path

Path	Consumer choice	Expected result
Renovate	Add the focused @ai-created/ui package rule to the consumer repository.	Eligible immutable tags produce reviewable pull requests.
Scheduled Renovate	Add a consumer-chosen schedule to that package rule.	Pull requests open during the preferred maintenance window.
Manual	Update the tagged dependency and regenerate the lockfile together.	The same review and compatibility contract applies without a bot.
No update	Keep the currently installed immutable tag.	The existing application remains unchanged.

Operational boundaries

No registration required

The design-system repository does not need to know which applications consume it. Teams may maintain their own inventory when useful.

Compatibility is consumer-owned

Each application defines the commands and environments that prove the release works with its stack.

Provider checks are separate

Deployment previews help review the product but do not replace consumer-owned compatibility checks.

Completion includes production

A green pull request is not the endpoint. Merge manually, confirm deployment, and verify the affected product workflow.

Monitoring reports rather than mutates

The optional currency check exposes a stale tag. It does not open, merge, deploy, or verify an update.

Recover by fixing forward

When compatibility or production verification fails, repair the consumer or publish a new patch. Never move a published tag or weaken a required check.

System health and exceptions

A mature library measures use, quality, and drift rather than equating inventory size with success.

Health signals

Signal	Question
Adoption	What share of eligible product surfaces uses the supported primitive or pattern?
Coverage	Which recurring product needs still require local implementations?
Quality	What accessibility, visual, reliability, and performance regressions recur?
Parity	Which design or code assets expose unmatched decisions?
Velocity	How long do proposals, reviews, migrations, and critical fixes take?
Trust	Can product teams predict behavior, ownership, and upgrade cost?

Exception policy

Record the need

State the unmet requirement, affected surface, and why composition fails.

Limit the blast radius

Keep the exception product-local and avoid naming it like a shared primitive.

Assign an owner and review date

Every exception expires, graduates, or is explicitly renewed.

Feed the system

Repeated exceptions become contribution evidence, not permanent forks.