Extend a design system

Design System

Start from what exists

• Inventory first: the project's tokens (CSS custom properties, Tailwind theme, SCSS variables, a theme object), its component folder and any component library. Extend those; never start a parallel system.
• Use existing components and tokens wherever they fit. When one almost fits, add a variant instead of copying it.
• Abstract from real repetition: a component or token appears three times, or twice with a clear plan to reuse it. One use case is not a system.

Token hierarchy

Three layers; each layer references only the one below it:

1. Primitives, raw values: --color-blue-500, --space-4, --font-size-lg, --radius-md. Named --{category}-{name}-{step}.
2. Semantic, the role in the UI: --text-primary, --text-secondary, --surface-default, --surface-elevated, --border-default, --interactive-primary, --interactive-primary-hover. Named --{role}-{variant}[-{state}].
3. Component, only where a component needs its own knob: --button-bg (from --interactive-primary), --button-radius (from --radius-md). Named --{component}-{property}[-{state}].

• Components use semantic or component tokens, never primitives or raw values. Name by purpose (text-muted), not by look (dark-gray).
• Scales instead of one-offs: spacing, a type scale with line heights, radii, shadows, and named z-index layers (dropdown, sticky, modal, toast).
• One naming style across all tokens (kebab-case); no circular references.
• Fold near-duplicates (#333 and #343434, 15px and 16px) into the nearest token instead of adding another.

Themes and dark mode

• A theme remaps the semantic tokens to other primitives; primitives and components stay untouched. Components never branch on the theme.
• Support light, dark and system (prefers-color-scheme), applied on the root element and remembered per user; follow live system changes when set to system.
• Check the contrast of every text and border pairing in every theme, and test every component in every theme. Respect reduced motion and high contrast settings.

Components and variants

• One clear responsibility and a small, typed API with sensible defaults. Prefer composition (children, slots, compound components) over many boolean props.
• Variants are one enum prop (variant: primary, secondary, outline, ghost, danger, link) plus a size prop (sm, md, lg, icon), each with a default. No boolean flags that can contradict each other.
• Shared behavior lives in the base: layout, focus-visible ring, disabled state (no pointer events, reduced opacity). Each variant sets only its colors through semantic pairs such as primary and primary-foreground.
• Build every state in: hover, focus-visible, active, disabled, loading, invalid, selected, plus empty content and overflow.
• Accessible by default: a native element underneath, an accessible name, keyboard behavior and focus handling where the pattern needs it.
• Style through tokens and the project's styling method; avoid !important and deep overrides of a library's internals.

Change it like an API

• A token or component change reaches every screen that uses it: find all usages and check the important ones.
• Treat renames and removals as breaking changes: deprecate first, name the replacement, migrate the call sites, then remove.
• Document each shared component where the project documents them (Storybook, a docs page): purpose, variants, one example. Update its stories or tests.
• When you consolidate duplicates, replace them in the same change if it stays small; otherwise list the remaining call sites.

Before you finish

• Existing tokens and components reused or extended; no parallel system.
• Primitive, semantic and component layers respected; no raw values in components.
• Variants and sizes are enums with defaults; all states covered.
• Every theme checked for contrast.
• Every usage of a changed token or component checked; docs updated.