Best Practices
Day-to-day guidance for designers and engineers — how to keep the system healthy as it scales.
Manifesto
“A design system is only as healthy as the people maintaining it. Do the boring thing well, every time — tokens, naming, states, states, states.”
01 · Golden rules
Six rules, zero exceptions
If you do nothing else, do these.
Tokens first
Reach for a token before inventing a value. Missing one? Add it upstream — don’t hard-code.
Semantic over raw
Use --color-primary, not --brandOS-primary-500. Semantic layers carry meaning; raw scales carry color.
Compose, don’t fork
Extend existing components via variants or composition. Forking splinters the system.
Theme at the root
Swap themes via data-brand / data-theme on <html>. Never per-component overrides.
Document exceptions
If you must diverge, record why and for how long. Schedule the convergence.
Small, legible PRs
Token renames and semantic shifts land safely when consumers can migrate incrementally.
02 · For designers
Designer playbook
Start from tokens
Bind every fill, type, spacing to a semantic variable in Figma before introducing a new value.
- Use semantic color styles.
- Pull the fluid type scale, don’t pick a bespoke size.
- Snap to the spacing scale — 4 / 8 / 12 / 16 / 24.
Name the way engineers read
Layers and components should match the documented vocabulary so handoff stays frictionless.
- Component name = React name = CSS class.
- State naming: default · hover · active · disabled.
- Prefix variants: size=md, tone=primary.
Annotate behavior
Document interactions, empty states, and error paths. Static mocks imply happy paths only.
- Loading skeletons.
- Empty-state copy.
- Error recovery path.
Pair early
Work with engineering when a pattern touches tables, async data, or permissions.
- Join the first spike.
- Review the token diff with the eng lead.
- Agree on breakpoint behavior before pixel polish.
03 · For engineers
Engineer playbook
No magic values
Use token-backed CSS variables. If a value is missing, add a token rather than hard-coding it.
- No hex literals in components.
- No px for spacing — rem via tokens.
- No inline style="" for visual properties.
Theme at the root
Switch themes via token sets on <html>, not scattered per-component overrides.
- Honor data-brand and data-theme.
- Use light-dark() for theme-adaptive values.
- Avoid Tailwind dark: variants — themes handle it.
Reuse before cloning
Extend system components through documented variants or composition before writing a new one.
- Check the component index first.
- Prefer slots over props for structural variance.
- Open a PR against @brandos/ui, not your app.
Cover every state
Loading, empty, error, and permission-denied are part of the UI contract — ship them all.
- Default + hover + focus + disabled.
- Loading skeleton, not a spinner where data fits.
- Empty state names the next action.
04 · PR checklist
Before you request review
- Every new value is a token, or falls back to one.
- Light + dark + Hackerman rendered without contrast regressions.
- Keyboard path works end-to-end (Tab, Enter, Esc).
- prefers-reduced-motion respected for any new animation.
- No hex / rgb literals in component source.
- Public component has a Storybook or showcase page.
- Changelog entry in @brandos/tokens for any token change.
- Screenshots attached at 1440px and 375px.
05 · Keep going