frontend-design-systems

Define tokens as TypeScript objects for colors, spacing, and typography, then expose them as CSS custom properties. Components reference tokens via var(--color-primary-500) or styled utilities, ensuring consistent values across the entire UI.

Use a variant prop mapped to style classes, or use class-variance-authority (CVA) to define variant and size combinations with default variants. This produces type-safe components like Button with primary, secondary, outline, and destructive styles.

Compound components attach subcomponents to a parent, such as Card.Header, Card.Body, and Card.Footer. This gives consumers flexible composition while the parent controls shared structure and styling.

Use controlled components when the parent must manage and validate state, and uncontrolled when the component manages its own state internally. A hybrid pattern checks whether a value prop is defined to support both modes.

Add role="dialog" and aria-modal="true", move focus into the dialog when it opens, trap focus among focusable elements, and close on the Escape key. Query focusable elements like buttons, inputs, and links to manage the focus order.

Avoid building a custom system for small projects or prototypes where an existing library suffices. Custom systems require ongoing token governance, documentation, and dark mode support, which adds maintenance overhead.