An end-to-end checklist for building a scalable, consistent, and maintainable design system, from design tokens and component libraries to documentation and team adoption.
A design system is only worth building if people use it. Most systems fail at adoption, not at design. Build the tokens, then the components, then the documentation that makes the right choice the easy one.
Foundations and tokens
- Define a colour palette with named roles, not raw hex values in components.
- Check every text and background pair against WCAG 2.2 contrast minimums.
- Define a type scale with a fixed ratio, and cap it at seven steps.
- Define a spacing scale on one base unit. Do not run two scales in parallel.
- Define radius, border and shadow tokens. Three shadow levels are usually enough.
- Define motion tokens: duration, easing and a reduced-motion fallback.
- Publish tokens in one machine-readable source that both design and code consume.
Component library
- List the components the product actually uses before you build any of them.
- Build the primitives first: button, input, select, checkbox, radio, link.
- Give every interactive component all its states: default, hover, focus, active, disabled, loading, error.
- Make focus states visible on every control, including on dark backgrounds.
- Define the responsive behaviour of each component, not just of the page.
- Handle the empty, loading and error state for every data-driven component.
- Test every component with long text, short text and no text.
Accessibility
- Use semantic HTML before reaching for ARIA.
- Confirm every component works with a keyboard alone.
- Confirm the tab order matches the visual order.
- Test the primary flows with a screen reader.
- Give every icon-only control an accessible name.
- Confirm no information is carried by colour alone.
Code architecture
- Agree the naming convention and write it down before the second component ships.
- Keep one source of truth per component. Delete the duplicates you find.
- Version the library and publish a changelog for every release.
- Add visual regression tests for the primitives.
- Set a bundle size budget and fail the build when it is exceeded.
Documentation and adoption
- Document each component with a usage rule and a “do not use when” rule.
- Show a live example next to the code snippet for every component.
- Record the decisions behind the system, so future teams do not relitigate them.
- Run a migration plan for the existing screens, in priority order.
- Name an owner. A system without an owner rots inside a quarter.
- Agree how a team proposes a new component, and who approves it.