claude-plugins/composer/templates/design-system/SKILL.md

---
name: <SLUG>-design-system
description: Design system for the <PROJECT NAME> project. Color tokens, typography, spacing, radii, shadows, density, motion, accessibility tokens, and component vocabulary. Load and apply whenever building UI for this project — generating mocks, writing components, picking colors, configuring Tailwind, styling native screens, building themes, designing CSS, or making any visual decision. The canonical visual reference for this project; if anything visible is being touched, this skill should be in context. Pairs with <SLUG>-interaction-design.
---

# <PROJECT NAME> design system

> **Status: <draft | reviewed | locked>**
> Generated by Composer's `ui-system` phase. Re-running that phase
> updates this skill (with confirmation on overwrite).

## How to use this skill

When generating or editing UI for this project — a mock, a real
component, a theme, a CSS file — read this SKILL.md and `tokens.ts`
first, then use the tokens. Never hardcode visual values. Don't
introduce new components without proposing them in `components.md`.

Sidecar files in this skill directory:
- `tokens.ts` — machine-readable token export. Import in mocks/code.
- `components.md` — component vocabulary, anatomy, states.

## Visual posture

<!-- One-sentence north star. -->

<TBD: visual posture sentence>

## Color

### Brand
- **Primary**: `<#hex>` — <name>
- **Secondary** *(if any)*: `<#hex>` — <name>

### Neutrals
- **Tone**: <warm | cool | true>
- **Scale**: 50 / 100 / 200 / 300 / 400 / 500 / 600 / 700 / 800 / 900 / 950
- See `tokens.ts` for hex values.

### Semantic
| Role | Light | Dark *(if dark mode)* |
|---|---|---|
| Success | `<#hex>` | `<#hex>` |
| Warning | `<#hex>` | `<#hex>` |
| Error   | `<#hex>` | `<#hex>` |
| Info    | `<#hex>` | `<#hex>` |

### Dark mode
- **Posture**: <yes | no | system-following>
- **Token mapping**: see `tokens.ts` `colorDark` (if applicable)

### Accessibility contrast
- **Target**: WCAG <AA | AAA>
- **Verified pairings** (against `neutral.50` light bg, `neutral.950` dark bg):
  - body text: <ratio> — ✅
  - UI components: <ratio> — ✅
  - <flag any below threshold>

## Typography

- **Display family**: <name>, weights <list>
- **Body family**: <name | "(same as display)">, weights <list>
- **Mono family** *(if used)*: <name>
- **Scale base**: <px>, ratio <1.125 | 1.2 | 1.25 | 1.333 | 1.5>
- **Sizes**: see `tokens.ts` `fontSize` — xs / sm / base / lg / xl / 2xl / 3xl / 4xl
- **Line-height**:
  - Tight (display): <value>
  - Normal (body): <value>
  - Relaxed (long-form): <value>
- **Letter-spacing** *(if customized)*: <values per size class>

## Spacing

- **Base unit**: <4px | 8px>
- **Scale (in base units)**: 0, 0.5, 1, 1.5, 2, 3, 4, 6, 8, 12, 16, 24
- See `tokens.ts` `spacing` for px values.

## Radii

- **Posture**: <sharp | tight | medium | pillowy | mixed>
- `sm` <px> · `md` <px> · `lg` <px> · `pill` 9999px · `full` 9999px

## Shadows & elevation

- **Posture**: <flat | subtle | generous>
- Scale: `xs / sm / md / lg / xl` — see `tokens.ts` `shadow`
- (Or "no shadows in this system" if posture is flat — use borders for elevation hierarchy.)

## Density

- **Default**: <comfortable | cozy | compact>
- **Padding tokens**: see `tokens.ts` `padding` — `tight / default / loose`
- **Component impact**: list components whose default density differs from the global default.

## Visual motion

- **Default duration**: <ms> (token: `motion.duration.default`)
- **Default easing**: <named curve> (token: `motion.easing.standard`)
- **Reduced-motion fallback**: linear, instant where appropriate

Behavioral motion (when things animate, what triggers them) is in the
**interaction-design** skill, not here.

## Accessibility tokens

- **Focus ring**: <style — solid 2px brand at 60% opacity / etc.>
- **Focus ring color token**: `color.focus`
- **Focus offset**: <px>
- **Hit-target minimum**: 44×44px (mobile) / 32×32px (desktop pointer)
- **Contrast targets**: WCAG <AA | AAA> — body 4.5:1, UI 3:1

## Components

See `components.md` in this directory for the full vocabulary, anatomy,
and state coverage. The TL;DR list of primitives:

- **Button** (primary / secondary / ghost / destructive / link)
- **Input** (text / textarea / select / checkbox / radio / toggle)
- **Card / Surface**
- **Badge / Tag**
- **Avatar**
- **Tooltip**
- **Modal / Drawer / Popover** *(behavioral patterns in interaction-design skill)*
- **Tabs**
- **Menu / Dropdown**
- **Toast / Notification**

Plus project-specific components from `ia.md`: see `components.md`.

## Theming variants

- **Multi-brand / tenant theming**: <yes | no — typically no for v1>
- **Theme-switching mechanism** *(if applicable)*: <CSS variables / data-theme attr / etc.>

## TBD on return

<!-- Any phases that were skipped or had unanswered questions in the
     ui-system interview. This is the worklist for the next pass. -->

- <TBD: ...>