Introduction
A design system without governance eventually becomes a dumping ground of inconsistent components. Governance defines who can contribute, how decisions are made, how changes are reviewed, and how the system evolves. It's the process layer that keeps your design system healthy.
Good governance balances control with velocity. Too strict, and teams work around the system. Too loose, and consistency erodes. The right model depends on your organization's size and culture.
This guide covers contribution models, decision frameworks, review processes, and metrics for design system health.
Key Concepts
Contribution Models
There are three common models for design system contributions:
- Centralized — A dedicated team owns the system. Others request changes. Best for consistency, worst for speed.
- Federated — Representatives from product teams contribute. Balance of ownership and speed.
- Open source — Anyone can contribute via PRs. Fastest adoption, needs strong review processes.
Decision Framework
markdown
# Component Addition Checklist
## Is it needed?
- [ ] Used by 3+ teams or products
- [ ] Solves a recurring pattern (not a one-off)
- [ ] Can't be composed from existing components
## Is it ready?
- [ ] API reviewed by 2+ consumers
- [ ] Accessibility audit passed
- [ ] Documentation complete
- [ ] Visual regression tests added
- [ ] Performance benchmarked
## Approval
- [ ] Design review (design system team)
- [ ] Code review (2 approvers)
- [ ] Breaking changes discussed in RFC
Practical Examples
1. RFC Process for New Components
markdown
# RFC: DataTable Component
## Problem
3 teams have built custom tables. Each handles sorting, pagination,
and filtering differently. Users experience inconsistent interactions.
## Proposal
Add a DataTable component with:
- Sortable columns
- Client and server pagination
- Column filtering
- Row selection
## API Draft
<DataTable
data={rows}
columns={columnDefs}
pagination={{ pageSize: 20 }}
onSort={handleSort}
/>
## Alternatives Considered
- Wrapping @tanstack/react-table (too low-level for most uses)
- Adopting team A's table (missing accessibility features)
## Timeline
- RFC review: 1 week
- Implementation: 2 sprints
- Migration guide: 1 week
2. Component Health Scorecard
javascript
// Automated health check
const scorecard = {
Button: {
accessibility: 'pass', // axe audit
documentation: 'complete', // all sections filled
testCoverage: 94, // percentage
bundleSize: '2.1kb', // gzipped
adoptionRate: 87, // % of teams using it
openIssues: 2,
},
DataTable: {
accessibility: 'partial',
documentation: 'incomplete',
testCoverage: 71,
bundleSize: '8.4kb',
adoptionRate: 45,
openIssues: 8,
},
};
3. Deprecation Process
markdown
## Deprecation Policy
1. **Mark as deprecated** — Add @deprecated JSDoc, console.warn in dev
2. **Migration guide** — Document the replacement and migration steps
3. **Grace period** — Minimum 2 minor versions before removal
4. **Codemod** — Provide automated migration where possible
5. **Removal** — Major version bump only
// Example deprecation warning
/** @deprecated Use `Button` with `variant="link"` instead. Will be removed in v4.0 */
export function LinkButton(props: LinkButtonProps) {
if (process.env.NODE_ENV === 'development') {
console.warn('LinkButton is deprecated. Use <Button variant="link"> instead.');
}
return <Button variant="link" {...props} />;
}
Best Practices
- ✅ Start with a contribution guide — lower the barrier to entry
- ✅ Use RFCs for significant additions — build consensus before building components
- ✅ Track adoption metrics — usage data drives prioritization
- ✅ Hold regular office hours for questions and feedback
- ✅ Automate quality gates (a11y, tests, docs) in CI
- ❌ Don't gate every small change — trust contributors for bug fixes and docs
- ❌ Don't ignore consumer feedback — the system exists to serve product teams
Common Pitfalls
- Building in isolation without consumer input — components don't fit real use cases
- No deprecation process — breaking changes surprise consumers
- Measuring output (components shipped) instead of outcomes (adoption, consistency)
- Governance too heavy for team size — a 3-person team doesn't need RFCs
Related Guides
- Design System Versioning — Release management and semver
- Design System Documentation — Making contributions discoverable
- Building Component Libraries — Technical contribution workflow
- Design Handoff Best Practices — Designer contribution processes