Design Systems skill for Codex

A design system is working when product teams reach for it first because it is faster than building their own, every component has one documented API and accessible behavior, and breaking changes arrive with a migration path. A Figma library with no code, or a package nobody imports, is not a system.

Before building

• Read AGENTS.md, the workspace layout (pnpm-workspace.yaml, turbo.json, nx.json) and how styling is done. The system must fit the existing stack, not replace it.
• Inventory before designing. Count duplicates; they set the priority list:

rg -l --glob '*.{tsx,jsx,vue,svelte}' -i 'function \w*(Button|Modal|Dialog|Select|Tooltip)\b' src | sort
rg -c '<button' --glob '*.{tsx,jsx}' src | sort -t: -k2 -nr | head
rg -o "from ['\"][^'\"]*(ui|components)/[A-Za-z]+['\"]" -N src | sort | uniq -c | sort -nr | head -30

• Screenshot every variant of the top five duplicated components side by side. The inventory board is the strongest argument for the system and the spec for v1.

Architecture

Layer	Contains	Changes how often
Tokens	Color, space, type, radius, motion, elevation (see design-tokens)	Rarely; themed per brand/mode
Primitives	Box/Stack, Text, Icon, VisuallyHidden, Slot	Almost never
Components	Button, Input, Select, Dialog, Tabs, Toast, Table	Minor releases
Patterns	Form layouts, empty states, page headers, filters	Often; can live in apps

Rules: components consume only semantic tokens, never raw values; patterns compose components and never restyle their internals; apps may build patterns but not fork components.

Foundations: build vs adopt

Need	Default
React, full styling control, accessibility handled	Headless: Radix Primitives or React Aria Components, styled with your tokens
React + Tailwind, want owned source	shadcn/ui as a starting point, copied into the package and then governed like your own code
Multi-framework or no framework	Web components (Lit) wrapping a headless core, or CSS-only components where behavior is trivial
Speed over identity, internal tools	Adopt a styled library and theme it via tokens; do not build

Never hand-roll a combobox, menu, dialog focus trap or date picker when a tested headless implementation exists; that is where accessibility bugs live.

Component API conventions

Write these down once and apply them to every component:

• variant for visual style (primary | secondary | ghost | danger), size for scale (sm | md | lg). No booleans like isPrimary, large.
• Composition over configuration: <Dialog><Dialog.Title/></Dialog> or slots, not fifteen props such as titleText, titleIcon, titleClassName.
• Pass through native props and refs (...props, forwarded ref or React 19 ref prop).
• asChild (Radix Slot) or a render prop for polymorphism, rather than an as prop that breaks types.
• Controlled and uncontrolled: value/onValueChange plus defaultValue.
• className accepted and merged last; styling escape hatches documented, not hidden.

import { cva, type VariantProps } from "class-variance-authority";
import { Slot } from "@radix-ui/react-slot";

const button = cva("inline-flex items-center justify-center gap-2 font-medium rounded-[var(--radius-control)] focus-visible:outline-2 focus-visible:outline-offset-2 disabled:opacity-50 disabled:pointer-events-none", {
  variants: {
    variant: {
      primary: "bg-[var(--color-action)] text-[color:var(--color-on-action)] hover:bg-[var(--color-action-hover)]",
      secondary: "border border-[var(--color-border)] bg-transparent hover:bg-[var(--color-surface-hover)]",
      danger: "bg-[var(--color-danger)] text-[color:var(--color-on-danger)]",
    },
    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" },
});

type ButtonProps = React.ComponentProps<"button"> &
  VariantProps<typeof button> & { asChild?: boolean };

export function Button({ asChild, variant, size, className, ...props }: ButtonProps) {
  const Comp = asChild ? Slot : "button";
  return <Comp className={button({ variant, size, className })} {...props} />;
}

Workflow for a new or changed component

- [ ] 1. Inventory existing usages and variants in the codebase
- [ ] 2. Write the component spec (template below) and get it reviewed
- [ ] 3. Build on a headless primitive with semantic tokens only
- [ ] 4. Stories for every variant, size and state; interaction tests for behavior
- [ ] 5. Accessibility check: keyboard path, axe, screen reader spot-check
- [ ] 6. Visual regression baseline
- [ ] 7. Changeset with the right semver bump
- [ ] 8. Migrate at least one real product usage before calling it done

Component spec template

# <Component>
**Purpose:** <one sentence; when to use, when NOT to use and what to use instead>
**Anatomy:** <parts and slots>
**API:** <props table: name, type, default, notes>
**Variants / sizes:** <list with intended use>
**States:** default, hover, focus-visible, active, disabled, loading, invalid
**Keyboard:** <keys and behavior, following the ARIA APG pattern>
**Content rules:** <label length, truncation, icon usage>
**Replaces:** <file paths of local duplicates to migrate>

Versioning and release

Use Changesets in a monorepo package:

npx changeset          # describe the change, pick patch/minor/major per package
npx changeset version  # bump versions, write CHANGELOG.md
npx changeset publish  # publish to the registry (ask the user before publishing)

Change	Bump
New component, new optional prop, new variant	minor
Bug fix, visual fix within spec	patch
Removed or renamed prop, changed default, changed DOM structure apps may target	major
Token value change that shifts layout or contrast noticeably	minor with release note; major if contrast or sizing contracts break

Publishing to a registry needs network and credentials; never run changeset publish or npm publish without explicit user confirmation.

Deprecation path

1. Mark the old API with /** @deprecated Use <Button variant="ghost"> instead. */ so IDEs strike it through.
2. Add a lint rule so new usages fail CI:

// eslint.config.js
rules: {
  "no-restricted-imports": ["error", { paths: [{
    name: "@/components/OldButton",
    message: "Use Button from @acme/ui (see docs/migrations/button.md).",
  }]}],
}

3. Ship a codemod for mechanical renames and run it in a dry run first: npx jscodeshift -t codemods/button-v2.ts src --parser=tsx --dry --print.
4. Remove in the next major only after usage reaches zero.

Governance

• Contribution model: anyone can propose (RFC issue with the spec template), the system team reviews API and accessibility, contributors can build with pairing.
• A component enters the system when two or more products need it; one-offs stay local.
• Weekly or per-release adoption metric:

rg -l "from ['\"]@acme/ui['\"]" apps | wc -l              # files using the system
rg -l "<button|styled\.button|className=.*btn" apps | wc -l  # files still hand-rolling

• Track in a table: component, adoption count, open bugs, local duplicates remaining.

Gotchas

• Shipping components that import app code or global CSS; the package must be leaf-level.
• className overrides that depend on specificity order; use cascade layers or a merge helper (tailwind-merge) so app overrides win predictably.
• Changing DOM structure in a minor: apps target internals in tests and CSS. Treat as major.
• Documentation that drifts: generate props tables from types (Storybook autodocs) instead of hand-writing them.
• Building every component before anyone uses one. Ship the top five by duplication count.

Output contract

When asked to set up or audit a system, return:

**Inventory:** <component>: <n local implementations> (files)
**Proposed layers and package:** <path, build tool, styling approach>
**v1 components (by duplication):** 1. ... 5.
**Conventions doc:** <path>
**Release/versioning:** <Changesets config path>
**Governance:** <RFC template path, review owners>
**Next migrations:** <files to migrate first>