Design System Rules

A design system is a contract, not a component library — every token, prop, and pattern you ship is a promise that consuming teams will build on, so changes must be deliberate and backward-compatible by default.

Tokens before components

• Define design tokens (color, spacing, typography, radius, elevation, motion) as the single source of truth before writing a single component — components consume tokens, they never hardcode raw values (#3B82F6, 16px) inline.
• Name tokens by role (color.background.danger, space.md), not by raw value or specific component (red-500, button-padding) — a role-based name survives a rebrand or theme change without renaming every consumer.
• Support at least light/dark theming through token swapping, not through component-level conditionals — a component that branches on theme === 'dark' internally has broken the abstraction.

Component API consistency

• Expose variation through a small, consistent set of props across all components: variant (visual style), size (dimensional scale), state (disabled/loading/error) — do not invent a new prop name for the same concept in different components (type in one, kind in another).
• Keep the same size scale (sm/md/lg, or a numeric scale) across every component that has a size — a Button and an Input placed side by side at "the same size" must actually render at the same height.
• Never let a component accept arbitrary style overrides (className escape hatches, inline style props) as the primary customization path — that defeats the system; add a real variant instead.

Composition over configuration

• Prefer composable primitives (Card, Card.Header, Card.Body) over a single mega-component with dozens of boolean props (showHeader, showFooter, headerVariant, ...) — composition scales to unanticipated layouts; prop explosion does not.
• Design compound components so consumers can reorder, omit, or wrap sub-parts without forking the component — a rigid single-component API forces a fork the first time a real design deviates slightly.
• Reserve configuration props for things that are genuinely binary or enum-like (a handful of states), not for arbitrary layout composition.

Documentation with live examples

• Every component's documentation page must include a live, interactive example — a static screenshot goes stale the moment the component changes; a rendered example cannot lie.
• Document the prop table with type, default, and a one-line description for every prop — an undocumented prop is effectively private even if it's technically exported.
• Include a "when to use / when not to use" section for components with overlapping purposes (e.g. Modal vs Drawer) — API shape alone doesn't tell consumers which one fits their use case.

Versioning and deprecation

• Follow semver strictly: a prop rename, a default value change, or a visual change that shifts layout is a breaking (major) change, not a patch — consuming teams rely on this signal to decide whether to review a bump.
• Never remove a prop or component in the same release that deprecates it — mark it deprecated (with a lint warning and a migration note), keep it functional for at least one full minor cycle, then remove it.
• Ship a changelog entry with every release describing the change and, for breaking changes, the exact migration path — "breaking change" with no instructions forces every consumer to read the diff themselves.

Contribution rules

• New components or token additions require a design review before merge — a "temporary" one-off component added without review becomes permanent tech debt the moment a second team copies it.
• Reject contributions that duplicate existing tokens or components under a new name ("just for this page") — redirect to the existing primitive or propose extending it instead.
• Any contribution that changes a shared token's value must audit and flag every component that consumes it — a token change is never scoped to "just one component" by definition.

Accessibility is not optional

• Every component ships with correct semantic HTML and ARIA attributes built in, so consuming teams get accessibility for free by using the system rather than having to bolt it on per-instance.
• Verify color token pairs (text on background) meet contrast requirements at the token level, once, rather than trusting every consumer to check contrast manually on every composition.
• Test keyboard navigation and focus states as part of a component's definition of done — a component that only works with a mouse is not finished.

Cross-platform consistency

• When the same design system spans web and native (or multiple frameworks), keep token names and values identical across platforms even though the implementation differs — a space.md token must mean the same physical spacing everywhere, or designers and engineers lose a shared vocabulary.
• Document any deliberate, unavoidable platform-specific deviation explicitly rather than letting it silently drift — an undocumented divergence gets "fixed" back into inconsistency by the next contributor who doesn't know it was intentional.