| name | design-system-governance |
| description | Contribution model, review lanes, and release cadence for mobile design systems. Use this when establishing or revising how changes enter the system. |
Design System Governance
Instructions
Governance is the set of rules that keep a shared design system shared. Without it, every team forks, every PR stalls, and tokens drift. Write the rules down, enforce them in CI, and keep them light enough that contributors use them.
1. Ownership Model
Pick one, and write it into CODEOWNERS:
- Centralized: a dedicated DS team owns tokens and components. Other teams open PRs; DS reviews and merges. Best for early-stage systems.
- Federated: product teams contribute under a DS maintainer council. Component reviews require a DS maintainer and the contributing team. Best once the system has > 3 contributing teams.
- Open-contribution with tiers: anyone can contribute patterns; primitives and tokens are centralized. Scales to many teams.
# CODEOWNERS
/tokens/ @org/design-system
/src/primitives/ @org/design-system
/src/patterns/ @org/design-system @org/contributing-team
/src/compositions/ @org/contributing-team
2. Contribution Lanes
Three lanes with explicit checklists. Write them as PR templates.
Lane A — Token change. Requires: design approval, contrast verification, migration note if semantic alias changes.
Lane B — New variant. Requires: variant matrix entry, snapshot matrix update, a11y contract update, changelog entry.
Lane C — New component. Requires: design spec link, anatomy doc, all-variant snapshots, a11y contract, per-platform API parity, docs page.
3. Review SLA
Commit publicly to review turnaround:
- Comment or approval within 2 business days of request.
- Reject fast: send contributors to an RFC thread rather than letting PRs stall.
- Use a maintainer rotation so no one person is the bottleneck.
4. RFC Process
For anything that touches the public API of the system (new token category, new component, API shape), require an RFC before code.
docs/rfcs/
├── 0001-introduce-motion-tokens.md
├── 0002-segmented-control.md
└── 0003-deprecate-neutral-tone-50.md
Template: problem, non-goals, proposal, alternatives, migration, open questions. Merge the RFC before the implementation PR opens.
5. Release Cadence
Pick a rhythm and stick to it. Minor releases every 2–4 weeks work well for active systems; patches as needed. Big-bang yearly releases demoralize everyone.
- Patch (x.y.Z): value tweaks, bug fixes, no API change.
- Minor (x.Y.0): additive tokens, components, variants.
- Major (X.0.0): removals, renames without alias, breaking API.
Automate release notes with Conventional Commits + changesets (or equivalent) so the changelog writes itself.
6. Deprecation Policy
Nothing is removed without a deprecation window:
- Annotate with
$deprecated: true and a replacement hint.
- Emit compile-time warnings on native platforms (
@Deprecated(...) on Compose, @available(*, deprecated, ...) on Swift, @Deprecated on Dart).
- Ship for at least one minor version before removal.
- Publish a codemod where feasible.
7. Metrics
Measure health to know where to invest:
- Adoption: % of screens using DS primitives vs. local re-implementations.
- Drift: count of hardcoded hex/px in consumer codebases.
- Escape velocity: time from RFC to merged implementation.
- Satisfaction: quarterly consumer survey (5 questions, no more).
Publish metrics quarterly. A DS that can't point to adoption numbers is flying blind.
8. Decision Log
Keep an ADR/ (Architecture Decision Record) folder:
docs/adr/
├── 001-style-dictionary-as-build.md
├── 002-three-layer-tokens.md
└── 003-compose-material3-baseline.md
Each ADR: context, decision, consequences. Revisited when consequences change.
9. Enforcement in CI
Governance that is not automated rots. Enforce:
- Token layer rules (lint).
- Changelog entry presence on PRs that change
src/ or tokens/.
- RFC link required in PR description for major changes.
- CODEOWNERS review required.
10. Anti-Patterns
- "Benevolent dictator" governance — the DS stops when that person leaves.
- Private Slack decisions that never hit the ADR log.
- Releases "when ready" — loses consumer trust.
- No escape valve for urgent product needs — teams fork and never come back.
- Governance docs nobody reads because they are 40 pages long.
Checklist
