20acf3ae9b
Validated against the plugin-dev:skill-development checklist and applied conformance fixes: Description style — all five skill descriptions now use the canonical "This skill should be used when..." third-person form, with expanded trigger-phrase coverage. Previously used imperative "Use when..." which the spec calls out as wrong. Writing voice — body prose changed from "You are the dispatcher / You walk a user through..." to imperative "Act as the dispatcher / Walk the user through...". Remaining "you" usage is confined to quoted output text the agent prints to the user, which is correct usage. Progressive disclosure — composer/skills/ui-system/SKILL.md was 2513 words (over the 2000-word ideal). Refactored to 1063 words by moving detailed phase content into: - references/design-interview.md (D1–D11 phase specifications) - references/interaction-interview.md (I1–I11 phase specifications) - references/inspiration-presets.md (Linear/Notion/Stripe/etc. table) The SKILL.md now points at each reference as needed; agents load only what's relevant for the current phase. Other four skills already within the 1000–2000 word range, no refactor needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
175 lines
7.7 KiB
Markdown
175 lines
7.7 KiB
Markdown
---
|
||
name: ui-system
|
||
description: Interviews the user to produce two project-local skills — a design-system skill and an interaction-design skill — that auto-load whenever UI work is in progress. Output goes to .claude/skills/<slug>-design-system/ and .claude/skills/<slug>-interaction-design/, NOT docs/planning/. The skills load themselves into context when anyone codes UI (mock or real); a plain reference doc would not. This skill should be used when the composer skill reaches phase 4 or 5, or when the user asks to "set up the design system", "specify interaction patterns", "configure UI tokens", "redo the UI system", or "define how the app looks and behaves".
|
||
---
|
||
|
||
# UI system
|
||
|
||
Run a focused interview that produces two project-local skills:
|
||
|
||
```
|
||
.claude/skills/<slug>-design-system/
|
||
├── SKILL.md ← canonical visual reference; auto-loads on UI work
|
||
├── tokens.ts ← machine-readable color / type / spacing / motion tokens
|
||
└── components.md ← component vocabulary with anatomy
|
||
|
||
.claude/skills/<slug>-interaction-design/
|
||
└── SKILL.md ← interaction patterns, state surfaces, input modes, i18n
|
||
```
|
||
|
||
Plus pointer stubs in `docs/planning/{design-system,interaction-design}.md`
|
||
so the planning index finds them.
|
||
|
||
## Why these are skills, not docs
|
||
|
||
A reference doc gets read once and drifts out of context as the
|
||
conversation grows. UI work later — generating a mock, writing a
|
||
component, picking a color — wouldn't have it loaded.
|
||
|
||
A skill with a UI-triggered description loads automatically every time
|
||
the trigger matches. The design system and interaction design must be
|
||
skills, full stop.
|
||
|
||
## Slug
|
||
|
||
Resolve in order:
|
||
1. `package.json` `name` — slugify.
|
||
2. Git remote name (e.g., `git remote get-url origin` → repo name).
|
||
3. Directory name.
|
||
4. Ask.
|
||
|
||
Slug rule: lowercase kebab-case, ASCII only.
|
||
`SourdoughTracker` → `sourdough-tracker` → `sourdough-tracker-design-system`.
|
||
|
||
## Interview shape
|
||
|
||
Two parts, **sequential**: design system first (visual), then interaction
|
||
design (behavioral). Don't interleave — they're different conversations
|
||
and the visual posture often informs interaction choices.
|
||
|
||
For each phase:
|
||
1. State what's being decided and why it matters (one line).
|
||
2. Show the default if there is one.
|
||
3. Ask the question. Batch related questions when they cluster naturally.
|
||
4. Confirm the answer back as it'll appear in the artifact.
|
||
5. Move on.
|
||
|
||
The user can answer **`default`** or **`skip`** at any phase:
|
||
- `default` → accept the offered default and move on.
|
||
- `skip` → mark `<TBD: ...>` and move on; user can revisit.
|
||
|
||
Never invent on the user's behalf. `<TBD>` is a worklist, not a failure.
|
||
|
||
## Phase 0 — Material ingestion (silent)
|
||
|
||
Before asking anything, scan for material the user already has. Read
|
||
without asking; surface findings before the first question.
|
||
|
||
| Source | What to extract |
|
||
|---|---|
|
||
| `package.json` | name (slug), version, dependencies (UI framework hints) |
|
||
| `tailwind.config.{js,ts}` | existing tokens, theme extensions |
|
||
| `tokens.{ts,json,css}` anywhere in repo | existing token values |
|
||
| `*.css`, `*.scss` | brand colors mentioned, font families imported |
|
||
| `index.html`, `<head>` of any HTML | font loads, color-scheme meta |
|
||
| `assets/`, `public/`, `docs/` for logos/screenshots | brand colors via image inspection |
|
||
| `README.md`, `BRANDING.md`, `STYLE.md` | style notes the user wrote |
|
||
| Existing `docs/planning/concept.md` | platform hint (web/mobile/native) |
|
||
|
||
Before the interview opens, summarize:
|
||
|
||
```
|
||
Material I found and will use:
|
||
• <thing> — <how it'll inform the interview>
|
||
Not found (will ask): brand color, type family, motion posture.
|
||
```
|
||
|
||
If the user has named a reference like *"make it look like Linear"* in
|
||
a previous Composer phase, surface it here and apply the matching preset
|
||
(see `references/inspiration-presets.md`).
|
||
|
||
## Part 1 — Design system
|
||
|
||
Run phases **D1 through D11** as specified in `references/design-interview.md`.
|
||
|
||
The phases cover, in order: visual posture (D1), color (D2), typography
|
||
(D3), spacing (D4), radii (D5), shadows (D6), density (D7), visual motion
|
||
(D8), components (D9), theme variants (D10), accessibility tokens (D11).
|
||
|
||
Read the reference for each phase before asking. Defaults and decision
|
||
guidance live there.
|
||
|
||
## Part 2 — Interaction design
|
||
|
||
Run phases **I1 through I11** as specified in `references/interaction-interview.md`.
|
||
|
||
Phases cover: input model (I1), state-surface declarations (I2 — most
|
||
important), motion (I3), breakpoints (I4), i18n (I5), state postures
|
||
(I6), time formatting (I7), keyboard (I8), optimistic updates (I9),
|
||
gestures (I10, touch-only), focus management (I11).
|
||
|
||
Skip I10 entirely if I1's primary input is not touch.
|
||
|
||
## Reference banks
|
||
|
||
When the user says "make it look like Linear / Notion / Stripe / etc.",
|
||
apply the matching preset from `references/inspiration-presets.md` as a
|
||
starting point. The user still confirms each value — presets seed the
|
||
conversation, they don't replace it. For "make it look exotic / brutalist
|
||
/ playful", ask for reference URLs and synthesize a posture sentence
|
||
rather than picking a preset.
|
||
|
||
## Write phase
|
||
|
||
After both interviews end, write all six files in one batch:
|
||
|
||
1. `.claude/skills/<slug>-design-system/SKILL.md` from `${CLAUDE_PLUGIN_ROOT}/templates/design-system/SKILL.md` — substitute slug, project name, and all interview answers.
|
||
2. `.claude/skills/<slug>-design-system/tokens.ts` from `${CLAUDE_PLUGIN_ROOT}/templates/design-system/tokens.ts` — fill in all values; `<TBD>` for skipped phases.
|
||
3. `.claude/skills/<slug>-design-system/components.md` from `${CLAUDE_PLUGIN_ROOT}/templates/design-system/components.md` — vocabulary matched to `ia.md`.
|
||
4. `.claude/skills/<slug>-interaction-design/SKILL.md` from `${CLAUDE_PLUGIN_ROOT}/templates/interaction-design/SKILL.md` — fill in all interview answers.
|
||
5. `docs/planning/design-system.md` from `${CLAUDE_PLUGIN_ROOT}/templates/planning-pointers/design-system.md`.
|
||
6. `docs/planning/interaction-design.md` from `${CLAUDE_PLUGIN_ROOT}/templates/planning-pointers/interaction-design.md`.
|
||
|
||
Then tell the user:
|
||
|
||
```
|
||
Wrote two project skills:
|
||
.claude/skills/<slug>-design-system/ (SKILL.md, tokens.ts, components.md)
|
||
.claude/skills/<slug>-interaction-design/ (SKILL.md)
|
||
|
||
These auto-load whenever UI work is happening. They should be available
|
||
immediately in this session; if the user is starting a new session in
|
||
this repo, they'll load on the first UI-related prompt.
|
||
|
||
Items still <TBD> (return-pass worklist):
|
||
• <list any phases that were skipped or had unanswered questions>
|
||
```
|
||
|
||
## Re-entry
|
||
|
||
When re-running the skill on a project that already has the artifacts:
|
||
|
||
1. Read both existing SKILL.md files plus tokens.ts and components.md.
|
||
2. List what's currently set; mark `<TBD>` items prominently.
|
||
3. Ask: "Update everything, just the TBDs, or pick a phase?"
|
||
4. Run only the chosen scope.
|
||
5. Always show a diff before writing.
|
||
|
||
## Hard rules
|
||
|
||
- **Always produce all six files.** Mocks can't proceed without them.
|
||
- **Always slug-namespace** so projects on the same machine don't collide.
|
||
- **`<TBD: ...>` rather than invent.** TBDs are the return-pass worklist.
|
||
- **Verify a11y contrast** before writing color tokens. Don't silently accept failures.
|
||
- **Honor `prefers-reduced-motion`** is policy, not opinion. Always declared as honored.
|
||
- **Confirm before overwriting** existing skill files on re-entry.
|
||
- **Tell the user what was written and where**, plus how to verify the skills load.
|
||
|
||
## References
|
||
|
||
Consult these files for detailed phase guidance:
|
||
|
||
- `references/design-interview.md` — full D1–D11 phase specifications with defaults
|
||
- `references/interaction-interview.md` — full I1–I11 phase specifications with defaults
|
||
- `references/inspiration-presets.md` — the Linear / Notion / Stripe / etc. preset table
|