๐จDesign Systems
17.1Structure: monorepo with a shared package
packages/
design-system/ # the component library
src/
components/ # Button/, Form/, Modal/, Table/ (each: .tsx, .stories.tsx, .test.tsx, index.ts)
tokens/ # colors, spacing, typography โ the single source of truth
utils/ # cn(), etc.
web-app/ # consumes @company/design-system via workspace:*
Tooling: pnpm/Turborepo/Nx workspaces. The app depends on the design system as workspace:*, so changes are picked up instantly in dev.
17.2Design tokens
Centralize colors, spacing, typography, radii, shadows as data. Everything references tokens โ change a token, the whole app updates. Expose them to Tailwind via config, or as CSS variables for runtime theming (see 10.5).
17.3Variant-driven components with CVA
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '../utils/cn';
const button = cva('inline-flex items-center rounded-md font-medium transition-colors disabled:opacity-50', {
variants: {
variant: {
primary: 'bg-blue-600 text-white hover:bg-blue-700',
secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
danger: 'bg-red-600 text-white hover:bg-red-700',
ghost: 'text-gray-700 hover:bg-gray-100',
},
size: { sm: 'h-8 px-3 text-sm', md: 'h-10 px-4', lg: 'h-12 px-6 text-lg' },
},
defaultVariants: { variant: 'primary', size: 'md' },
});
interface Props extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof button> {}
export const Button = React.forwardRef<HTMLButtonElement, Props>(
({ className, variant, size, ...props }, ref) => (
<button ref={ref} className={cn(button({ variant, size }), className)} {...props} />
)
);
Button.displayName = 'Button';
Why CVA: type-safe variant combinations, zero runtime cost (classes resolved at build), pairs perfectly with Tailwind, trivially extensible. Always forwardRef so consumers can attach refs, and spread ...props so native attributes (aria-*, onClick) pass through.
17.4Compound components for complex UIs
For forms/tables/modals, expose composable sub-components so teams build flexibly without you anticipating every layout:
<Form {...methods}>
<Form.Field error={errors.email?.message} required>
<Form.Label>Email</Form.Label>
<Form.Input {...register('email')} />
</Form.Field>
<Form.Submit>Create</Form.Submit>
</Form>
Each piece is accessible by default; teams compose them; you don't ship 40 props on one mega-component.
17.5Multi-tenant theming
Provide tokens as CSS variables through a ThemeProvider; components read var(--color-primary) etc. Each org/customer can override the variable values without forking components:
function ThemeProvider({ theme, children }) {
return (<><style>{`:root{--color-primary:${theme.colors.primary};/* ... */}`}</style>{children}</>);
}
17.6Feature flags without spaghetti โ composition over conditionals
The failure mode: nested flags.x ? ... : ... scattered inside components. The fix: flags choose which component variant to render, they don't fragment a component's internals.
// Instead of conditionals inside one component:
function TicketCard({ ticket }) {
const useNew = useFlag('newTicketLayout');
return useNew ? <TicketCardNew ticket={ticket} /> : <TicketCardLegacy ticket={ticket} />;
}
Benefits: each variant is independently testable and Storybook-able; removing the old variant post-rollout is a clean delete; no branching maze. Use separate contexts for flags vs theme so they don't cross-trigger re-renders. Resolve flags server-side during auth (LaunchDarkly etc.) and provide them via context.
17.7Flexible component APIs (render props + config)
A List that renders as list/grid/table via a variant prop plus a renderItem render-prop or a columns config serves many features from one component โ without bloating any single call site.
17.8The rest of a real design system
- Storybook โ every component + every variant + feature-flag/theme permutations documented and visually testable. This is how teams discover what exists (prevents duplicate Buttons).
- Testing โ unit (Testing Library), accessibility (axe-core / Storybook a11y addon), visual regression (Chromatic/Percy).
- Accessibility baseline โ WCAG 2.1 AA: keyboard operability, focus management, ARIA where needed, color contrast. Consider building on headless primitives (Radix UI, React Aria) so accessibility is handled for you.
- Versioning โ semver; breaking changes only in majors; deprecation window (e.g., 2 minor releases) with migration guides; automated publish + changelog.
- Governance โ design/eng agreement before adding components; a11y + TS-strict + test-coverage gates in review; clear ownership.
๐ง Quiz: Design Systems
2 questions1Design tokens are:
2The 'compound component' pattern is used to: