ResourcesContribution model
Contribution model
How to add to the design system. Three tiers of change, three review cadences, and one rule: tokens are sacred.
The three tiers
Every change to the system is one of three tiers. The tier determines the review cadence and the bar for approval.
| Tier | Examples | Review |
|---|---|---|
| Patch | Bug fix in a component, copy fix in the docs, alt text fix on a screenshot | 1 reviewer, 1 day |
| Minor | New component in an existing group, new variant on an existing component, new page in an existing section | 1 reviewer, 3 days |
| Major | New token, new component group, new section in the docs, change to the design language itself | 1 reviewer + 1 design lead, 7 days |
Sacred tokens
The 8 color tokens, the 6 type sizes, the 13 spacing tokens, the 3 radii, and the 3 shadows are sacred. They are the system. Changing a sacred token is a Major change, by definition, and it must be argued in a written RFC before any code is touched.
The contribution flow
- Open an issue. The issue is the argument. State the change, the rationale, the alternatives considered, and the roll-back plan.
- Wait for the design review. A maintainer will review the issue within 1-3 days. The review is a public discussion, not a gate.
- Open a PR. The PR references the issue. The PR description restates the argument in one paragraph.
- Iterate. Review comments are public. Every comment is a chance to clarify the argument; not every comment is a blocker.
- Merge and document. The merge includes the changelog entry. The docs are updated in the same PR. A change without docs is not merged.
The code of conduct
The discussion of a design system is itself a design system. The comments are read by future contributors. They are written in the same voice as the docs. They disagree with arguments, never with people. They cite the principles. They use do/don't to clarify.