Design the system first so features stay visually coherent.
Token Layers
- Foundations -> color, spacing, radius, shadow, motion, typography, z-index
- Semantic tokens -> surface, text, border, accent, success, warning, danger
- Component tokens -> button, input, card, table, dialog, nav
Design Rules
- Prefer semantic tokens over hard-coded hex values in components.
- Keep spacing and sizing on a predictable scale.
- Use a limited typography ramp with explicit text roles.
- Define default, hover, active, focus, disabled, loading, error, and success states for interactive components.
- Treat empty/loading/error states as first-class UI, not afterthoughts.
Responsive Rules
- Design mobile-first unless the feature is desktop-only by requirement.
- Change layout before shrinking text to preserve readability.
- Keep touch targets and focus rings visible at all breakpoints.