design-system · git:20260909.7803b00 · 2026-09-09 · sha256 cd2606d0dbb7efde

design-system git:20260909.7803b00A

Immutable. This exact content never changes and is served at /api/v1/blob/cd2606d0dbb7efde.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_mq35cdzxucgoeugb/cd2606d0dbb7efde3e9a6a41ab59a9fdaa2d70905506a16ac454f4c594529c20.json

Then /plugin install design-system@markdownregistry-mq35cdzxucgoeugb in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: design-system
description: Build or improve reusable web design tokens, themes, component variants, and component-state coverage using the repository's CSS/Tailwind, headless UI, shadcn/ui, or Storybook conventions. Use for shared UI consistency and component-system work, not an isolated page restyle or a broad accessibility audit.
---

# Design system

Make shared visual and interaction decisions explicit without turning one page into an unnecessary framework. Inspect existing tokens, components, stories, theme providers, and representative consumers first.

## Find the source of truth

Use [modern web targets](../web-standard/references/modern-targets.md): current stable platform features and framework/tool versions, with backward compatibility only for explicit requirements.

Identify the framework/version, styling system, component primitives, icon family, and token ownership. Preserve existing APIs and local component changes. A Figma library or screenshot can inform design, but repository behavior and implementation constraints still need inspection. Do not claim a design matches an unavailable reference.

Read [framework integration](references/frameworks.md) when Tailwind, shadcn/ui, headless primitives, or Storybook are involved. Use `frontend-design` for visual direction, `svg-design` for icon consistency, and `web-animation` for motion tokens and lifecycle.

When changing global base styles or integrating a component library, read
[CSS normalization and resets](../web-standard/references/css-baselines.md). Keep
one baseline owner and verify its effect on the shared component states.

## Tokens and component boundaries

- Distinguish raw palette/scale values from semantic roles such as surface, text, border, accent, danger, and focus. Add a token when multiple consumers share a decision, not merely to rename every literal.
- Define light/dark and interaction-state mappings together. Check actual foreground/background pairs and focus visibility. Avoid a global color substitution that erases state or brand meaning.
- Keep typography, spacing, radii, elevation, density, and motion scales coherent with the existing system. Derive fluid behavior from content and layout constraints rather than an arbitrary breakpoint catalog.
- Expose variants that represent real usage. Prefer a small composable API to a growing collection of booleans that permits invalid combinations.
- Preserve ref forwarding, event composition, semantic elements, controlled/uncontrolled behavior, and keyboard/focus contracts when wrapping a primitive. A styled replacement is not behavior-equivalent merely because it looks the same.
- Migrate representative consumers before claiming a shared fix is complete. Keep compatibility aliases only when they support an actual transition, with a clear removal condition.

## State coverage

Select relevant states from enabled, hover, focus-visible, pressed, selected, disabled, loading, empty, error, success, long content, and overflow. For overlays, include open/close, Escape, focus return, scroll locking, and portal stacking. Do not create snapshots for impossible combinations.

Verify narrow/wide containers, text zoom/reflow, themes, reduced motion, and right-to-left layout when supported. Distinguish component container width from the browser viewport. Use logical CSS properties when direction changes are in scope.

Use [internationalization](../internationalization/SKILL.md) when shared components need translated messages, bidirectional content, international input, or script-specific layout verification.

Build stories or examples in the existing harness so the next change can reproduce these states. Use semantic queries and user interactions for behavioral tests. A screenshot assertion cannot prove focus trapping or a callback contract.

Use `forms-and-data-state` for submission and async data lifecycles behind shared control states. Keep the component's visual API separate from ownership of server data and drafts.

Use `web-standard` when choosing native dialogs, popovers, forms, or other primitives with browser-owned behavior. Preserve the existing component's contract and verify behavior in current target engines and any explicitly required compatibility path before replacing it.

## Verify and deliver

Run the repository's component tests, style/type checks, and visual comparisons for affected consumers. Inspect actual captures with `cli-web-evidence` or `responsive-web-capture`. Use `accessibility` for interaction/semantics findings. Automated accessibility results do not establish complete conformance.

Report token/API changes, migrated consumers, demonstrated states, and remaining compatibility gaps. Do not regenerate a component library, install Storybook, or adopt a new styling framework for a small consistency fix unless that change is needed and within scope.