Design System Engineering Principles

# Design System taste of a pragmatic design systems engineer - Define design tokens for color, spacing, typography, radius and motion in one source file, and generate CSS variables and platform outputs from it. Confidence: 0.90 - Name tokens by purpose, such as color-text-muted or space-inset-md, not by raw value like gray-500 or 16px. Confidence: 0.85 - Support light and dark themes by swapping semantic token values, never by overriding individual component styles. Confidence: 0.90 - Build components on accessible headless primitives such as Radix UI or React Aria instead of re-implementing focus and keyboard logic. Confidence: 0.85 - Meet WCAG 2.2 AA contrast for every token pairing and check it automatically when tokens change. Confidence: 0.90 - Keep the component API small: a few well-named variants and sizes beat dozens of boolean props. Confidence: 0.85 - Prefer composition with slots or children over configuration objects for complex components like dialogs and menus. Confidence: 0.80 - Forward refs and spread remaining props onto the root element so components work with forms, tooltips and tests. Confidence: 0.85 - Never hard-code colors, spacing or font sizes inside components; lint for raw values with Stylelint or an ESLint rule. Confidence: 0.85 - Document every component in Storybook with usage guidance, do and don't examples, and live controls. Confidence: 0.85 - Run visual regression tests with Chromatic or Playwright screenshots on every pull request. Confidence: 0.80 - Run automated accessibility checks with axe in component tests, and still test keyboard and screen reader flows by hand before release. Confidence: 0.85 - Publish the library as a versioned package with semantic versioning and a changelog generated by Changesets. Confidence: 0.90 - Treat a renamed prop or removed variant as a breaking change, and ship codemods for large migrations. Confidence: 0.75 - Deprecate before removing: mark the old API, log a development-only warning, and remove it in the next major version. Confidence: 0.85 - Ship ESM with tree-shakeable per-component entry points and mark CSS files as side effects correctly. Confidence: 0.80 - Respect prefers-reduced-motion and keep motion tokens short and purposeful. Confidence: 0.80 - Keep icons as a separate package of optimized SVG components with consistent size and stroke tokens. Confidence: 0.75 - Use logical CSS properties like margin-inline-start so components work in right-to-left layouts. Confidence: 0.75 - Keep Figma components and code components in sync by sharing token names and reviewing drift every release. Confidence: 0.70 - Measure adoption by scanning product repositories for library imports and one-off overrides. Confidence: 0.65 - Accept contributions through a short proposal template that covers the use case, API and accessibility before any code. Confidence: 0.70