Frontend design system practices: tokens, typography, color, layout, and component consistency.
<when_to_use>
Creating or updating a design system for web UI
Defining visual foundations before implementation
Aligning design decisions between design and engineering
Reviewing UI consistency and scalability risks
</when_to_use>
<input_requirements>
Product context and target platforms (web/mobile web/desktop web)
Brand constraints (colors, typography, tone)
Accessibility target (e.g., WCAG 2.2 AA)
Existing design system or UI kit
Current component library and theming model
</input_requirements>
<core_principles>
Use design tokens as the single source of truth; avoid hardcoded visual values in components
Structure tokens by layers: primitive, semantic, and component-level
Model color as semantic roles (surface, text, accent, status) instead of standalone palette usage
Meet required contrast ratios for text and key UI elements
Use a consistent type scale and spacing scale for hierarchy and rhythm
Use responsive grid rules and explicit breakpoints/window classes; do not design for fixed devices only
Define component variants and states (default, hover, focus, active, disabled, loading)
Keep component APIs minimal and reusable; avoid one-off visual patterns without system value
Document handoff artifacts: token mapping, component anatomy, and edge-case behavior
</core_principles>
Token inventory exists and covers color, typography, spacing, radius, elevation, motion
Semantic tokens are mapped to UI roles and component parts
Typography rules include font sizes, line-height, and usage contexts
Layout rules define container widths, columns, gutters, and responsive behavior
Interactive states are specified for all actionable components
Dark/light or themed variants use tokens, not duplicated raw values
<quality_rules>
Every visual rule is testable in design or implementation review
System-level changes include migration impact for existing components
Design decisions are traceable to tokens and component contracts
Exceptions are documented with scope and expiration criteria
</quality_rules>
<do_not>
Do not hardcode colors, spacing, or typography in feature-level UI
Do not introduce new variants before checking existing system patterns
Do not approve components without focus and disabled states
Do not overload the token set with near-duplicate values
</do_not>
<output_requirements>
List chosen foundations (tokens, typography, color roles, layout rules)
List component patterns and required states
List known risks and consistency trade-offs
Provide references to standards and system guidance used
</output_requirements>
Design Tokens Community Group
WCAG 2.2
WCAG Contrast Minimum
Material Design Color Roles
Material Design Typography
USWDS Design Tokens
Atlassian Foundations
web.dev Responsive Web Design Basics
