movq/claude-plugins
2
0
Fork 0
Code Issues Pull Requests Actions Releases Activity
Files
20acf3ae9b33e412b63827dce9ef35b4252381bd
claude-plugins/composer/skills/ui-system/SKILL.md
movq 20acf3ae9b chore(composer,symphony): align skills with skill-development spec 
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>
2026-04-29 22:10:14 -05:00

7.7 KiB
Raw Blame History

name, description
name description
ui-system 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
Reference in New Issue View Git Blame Copy Permalink