How to Contribute
The system gets better when product teams share what they keep rebuilding, push back on what doesn’t fit, or write down a call worth remembering. Most contributions start with a message — not a pull request.
Start here
Three ways most asks begin. Pick the one that matches the shape of what you have.
Spotted something off?
A typo, a broken link, a screenshot that didn’t render, a heading that contradicts the principle below it — ping Sergio in Teams or send an email. One sentence is enough to start.
Want something added or changed?
A pattern you keep rebuilding, a missing variant, an anti-pattern you wish was documented, a token that doesn’t cover your case — share what you’re trying to do. The shape of the change is the conversation, not a finished spec.
Made a call worth remembering?
Chose teal over green for a status, replaced a library, scoped a feature down — write it up so future contributors don’t relitigate it. The Decision Log captures the why, not just the verdict.
Where the system grows
Six places contributions tend to land. You don’t need to know which one your ask belongs to before reaching out — naming the area is the conversation.
Tokens
The visual vocabulary — colors, type, spacing, motion. If your work needs a new token or pushes against an existing one, that’s a useful signal back into the system.
Foundations and brand pages
The long-form teaching docs — color, motion, typography, accessibility, brand voice. If something is missing, unclear, or stale, that’s the contribution.
Components
New components, variants, or states. The system grows fastest when product teams report what they had to build themselves.
Patterns
Composed UI — form layouts, navigation, empty states, data tables. Patterns reference components and tokens but don’t introduce new primitives.
Anti-patterns
What not to do, with the principle being violated and the correct alternative. Add an entry when you catch something in review you wish a coding agent had caught earlier.
Decision log entries
ADR-style records of material decisions. Six fields, no shortcuts — see the Decision Log for the schema and live entries.
What happens after you reach out
Four beats, the same shape whether it’s a typo fix or a new foundation.
Send it.
Teams DM or email Sergio. A sentence about what you’re trying to do beats a polished spec — the system gets better when the conversation starts early.
We sync on shape.
Sergio responds with a scope, an ETA, or a clarifying question. If we disagree on the approach, that’s the most useful conversation in the thread — the trade-off goes into the writeup so the next person doesn’t have to relitigate it.
It lands as a real change.
Tokens regenerate, the site rebuilds, the Agent Kit refreshes. You’ll see the change in the Changelog when it ships.
Decisions get written down.
If the change overrides a prior call or sets a new constraint, an entry lands in the Decision Log alongside it. That’s how the system stays defensible six months from now.
When a change deserves a Decision Log entry
Most asks don’t need one. A new entry is warranted when the change overrides a prior decision, adds a constraint that wasn’t there before, or settles a question reviewers will want to revisit in six months. The test is simple: if you can imagine a future contributor undoing this work because they didn’t know the reasoning, log it. See the Decision Log for the schema and live entries.
If you have repo access
Most consumers won’t, and don’t need to — the intake above covers it. If you do work in the repo directly, here’s the shape of a code-level contribution.
Where things live
- Tokens
tokens/global/*.json, tokens/semantic/*.json - Foundations & brand
src/app/foundations/<name>/, src/app/brand/<name>/ - Components
src/app/components/<name>/ (docs), src/components/ui/<Name>.tsx (impl) - Patterns
src/app/patterns/<name>/ - Anti-patterns
data/anti-patterns/<category>.json - Decisions
data/decisions.json
How a code change moves
PR for fixes, GitHub issue first for proposals. Keep PRs focused — one concern per PR makes review faster and rollbacks cleaner. Reviewers point at the Design Principles, Anti-Pattern Catalog, and Accessibility page as the bar; agent guidance, semantic token use, and a Decision Log entry on overrides round out what gets checked.
What the tooling catches
Four guardrails run before a human looks. npm run audit:tokens flags raw hex or pixel values, npm run typecheck blocks merge on TS errors, npm run lint catches common React and accessibility mistakes, and npm run build exercises the full static export plus token, Agent Kit, asset library, and Pagefind builds.
No self-merge
JM Family policy: every merge requires a reviewer other than the author. If you’re the only person available, the change waits — the bar is the bar.
Get in touch
Sergio Urrunaga — design system owner
Teams is the fastest channel for quick questions. For anything bigger, email so the ask has a durable home.