Design Systems

Instructions

3-Tier Design Token Architecture

• Tier 1 — Primitive Tokens: Raw values with no semantic meaning. These are the palette.
• color.blue.500 = #3B82F6
• spacing.4 = 16px
• font.weight.600 = 600
• Tier 2 — Semantic Tokens: Purpose-bound aliases that reference primitives. These carry intent.
• color.interactive.primary = {color.blue.500}
• spacing.component.gap = {spacing.4}
• color.feedback.danger = {color.red.600}
• Tier 3 — Component Tokens: Scoped to a single component. These enable per-component theming.
• button.background.default = {color.interactive.primary}
• button.background.hover = {color.blue.600}
• input.border.error = {color.feedback.danger}
• Naming Rule: Name tokens for what they ARE, never what they LOOK LIKE. Use color.danger not color.red. Use spacing.compact not spacing.8.

Component Library Standards

• Ship Criteria: Every component ships with a default variant, all interactive states (default, hover, active, focus, disabled), all size variants (sm / md / lg), and light & dark theme support. No exceptions.
• Composition First: Build small, combinable units. A Card composes CardHeader, CardBody, CardFooter — not a single monolith with 20 props.
• Consistent Props: Use sm / md / lg — never small / medium / large. Boolean props use is- prefix (isDisabled, isLoading). Event props use on- prefix (onClick, onClose).
• Triad Rule: Each component must have a Figma source component, a Storybook story, and a written usage guideline. Missing any one means the component is not done.
• Versioning: Use semver. Breaking prop changes or removed variants require a major bump. New variants or props are minor. Bug fixes are patch.

Pattern Library

• Categories: Organize patterns into Forms (input groups, validation, multi-step), Navigation (tabs, sidebars, breadcrumbs, command palettes), Data Display (tables, cards, lists, stats), Feedback (toasts, modals, alerts, progress), and Onboarding (empty states, walkthroughs, tooltips).
• Each Pattern Documents: The problem it solves, when to use it, when NOT to use it, which components compose it, and a real-world example.

Documentation Per Component

• Required Sections: Overview, When to Use, When NOT to Use, Variants (with visual examples), Props table (name, type, default, description), Accessibility notes (ARIA roles, keyboard behavior), and Code examples (common and edge-case usage).
• Changelog: Maintain a per-component changelog. Every change gets a date, version, and description. Breaking changes get migration instructions.

Governance

• Build tokens before components — the token layer is the foundation
• Include QA engineers and frontend developers in every design system review
• Version the Figma library with the same semver as the code library
• Wait for the third use case before abstracting a pattern into the system
• Light AND dark theme support from the very first component — retrofitting is expensive
• Never leave a component undocumented; undocumented components get misused
• Publish a contribution guide: how to propose a new component, review criteria, and approval workflow