---
name: design-system
description: Reference for <DESIGN SYSTEM NAME> — component catalogue, token names, composition rules, and migration paths. Use when building UI, choosing a component, or resolving a token name.
license: MIT
---

<!--
  Destination: .claude/skills/design-system/SKILL.md
  Also read from .github/skills/ and .agents/skills/ by other tools.

  Only six frontmatter fields are portable across the Agent Skills standard:
    name, description, license, compatibility, metadata, allowed-tools
  Everything else is a vendor extension and will hard-fail on upload
  elsewhere. This file uses three of them.

  The reason to put reference material here rather than in AGENTS.md: only
  the name and description sit in context until the skill is actually used.
  A 2,000-line component catalogue costs you nothing on the turns that do not
  need it. AGENTS.md is billed on every turn, forever.

  So: rules that always apply -> AGENTS.md. Reference material and multi-step
  procedures -> here.
-->

# <DESIGN SYSTEM NAME>

## Choosing a component

<A decision tree, or a table mapping intent to component. This is the part
worth writing at length, because it is the part that stops an agent building
its own version of something you already ship.>

| I need to… | Use | Not |
|---|---|---|
| `<take a short text input>` | `<TextField>` | `<a bare input>` |
| `<show a transient message>` | `<Toast>` | `<Alert, which is persistent>` |

## Token reference

<Full token names and what each is for. Semantic roles first, primitives last
— an agent shown `blue.500` will use `blue.500`.>

## Migrations

<Old API -> new API, with the version the change landed in. Agents reach for
deprecated APIs at a structural rate, because old code outnumbers new code in
almost every repository. A machine-readable replacement pointer fixes this at
the retrieval layer, where a prose warning does not.>

## Verification

After generating UI, run `<pnpm typecheck && pnpm lint>` and fix what fails.
Do not report completion before both pass.