design-system-governance

Design System Governance — UDS Skill

Use this skill when the user needs governance, scaling, or adoption guidance for a design system — including centralized vs federated models, lifecycle, contribution rules, and how the Universal Design System fits as a single source of truth with palette overrides for brands.

When to Use

• User is deciding how to govern a design system (who decides, how contributions work).
• User is scaling across multiple teams or products.
• User is comparing centralized vs federated vs hybrid governance.
• User wants a contribution or adoption process (proposal → stable → deprecation).
• User is planning multi-brand or multi-product use of the same system.

Governance Models

• Centralized: One team owns the system; other teams consume. Works well early and for single-product companies. Can become a bottleneck when many products or brands have conflicting needs (accessibility, brand, features).
• Federated: Representatives from different products/brands share decision-making. Better for diverse portfolios and different maturity levels. Requires clear decision frameworks and a mix of skills (design, eng, a11y, product).
• Hybrid: Core system is centralized (tokens, base components); product- or brand-specific extensions or separate surfaces are federated. UDS fits this: one token/component foundation, palette overrides and optional custom palettes per brand.

UDS as Single Source of Truth

• Tokens: tokens/design-tokens.json — one file. Foundation tokens (spacing, motion, typography scale, z-index) are locked; palette tokens (color, shadow, radius, display font) vary per palette. Custom palettes can be added via palette.py create and merged into the same structure.
• Components: src/data/components.csv and implementation (React/Vue/Svelte) — one canonical set. Variants and states are defined once; products use the same components with different data-theme (palette).
• Rules: src/data/ui-reasoning.csv — sector/product-type rules (e.g. IF sector=finance THEN palette=corporate). Governance can extend this with org-specific overrides or leave it as-is for recommendation only.

Component Lifecycle (UDS)

UDS uses a defined lifecycle for components. Reference docs/governance/LIFECYCLE.md:

Stage	Meaning
Proposal	RFC, discussion, acceptance criteria
Alpha	Initial implementation; API may change; limited a11y
Beta	API stabilizing; a11y audit; documentation draft
Stable	API frozen; WCAG 2.2 AA; docs and examples complete; cross-palette tested
Deprecated	Migration guide; maintained 2 major versions; then removed

Promotion: Proposal → Alpha (RFC + impl), Alpha → Beta (API review + basic a11y), Beta → Stable (full a11y, docs, 2+ palette tests), Stable → Deprecated (replacement + migration guide).

Use this lifecycle in your own governance: e.g. new components start as Proposal, reach Stable only after a11y and docs, and deprecation is time-bound.

Contribution and Adoption

• Contribution: Define how proposals are submitted (RFC, issue template), who reviews (design + eng + a11y), and how changes land (PR to design-tokens.json, components.csv, code). UDS does not prescribe a specific tool (GitHub, Notion, etc.); use what fits your org.
• Adoption: Onboard teams with: (1) install/setup (e.g. uds install, tokens in repo), (2) palette choice per product (data-theme), (3) component usage from the canonical list, (4) docs/Storybook for usage. Design ops can track adoption (e.g. token usage, component usage) to find gaps and deprecations.

Multi-Brand and Multi-Product

• One system, brand layers: Use one design system with multiple palettes (UDS has 9; add custom via palette.py). Each product or brand sets data-theme to its palette. Single documentation and one codebase.
• Separate systems: Only if teams need fully independent workflows, review processes, or branding. Heavier to maintain; consider hybrid first (core shared, surfaces or themes separate).

Quick Reference

Topic	Reference
Component lifecycle	docs/governance/LIFECYCLE.md
Token architecture	CLAUDE.md or project Token Architecture section — foundation vs palette
Custom palettes	python src/scripts/palette.py create/list
Rules and reasoning	src/data/ui-reasoning.csv

Governance should keep the design system predictable (lifecycle, tokens, components) while allowing controlled extension (palettes, rules) for multi-team and multi-brand use.