โšกLearnIT
Architecture ยท Topic 17

๐ŸŽจ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 questions

1Design tokens are:

2The 'compound component' pattern is used to:

Answered 0/2