claude-plugins/composer/skills/ui-system/SKILL.md

name, description

name

description

ui-system

Interview the user and 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. Currently a placeholder skill that captures the minimum needed for downstream phases to proceed; planned for a fuller specification pass. Use when the composer skill reaches phase 4 or 5, or when the user asks to "set up the design system" or "specify interaction patterns."

UI system (placeholder)

Status: PLACEHOLDER. This skill currently captures the minimum design-system and interaction-design content needed for the mocks phase to proceed. A fuller specification pass is planned. When the user returns to flesh this out, expand the interview sections below and the SKILL.md / sidecar templates.

Why this is a skill, not a doc

A reference document at docs/planning/design-system.md gets read once and then drifts out of context as the conversation grows. UI work that happens later — generating a mock, writing a component, picking a color — won't have it loaded.

A skill with a description that triggers on UI work is loaded automatically every time the trigger matches. That's the whole point of the skill mechanism. The design system and interaction design must be skills.

What this skill produces

Two project-local skills, plus their sidecar data files:

.claude/skills/<slug>-design-system/
├── SKILL.md        ← the skill itself; 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

And two stub pointer files in docs/planning/ so the planning index finds them:

docs/planning/design-system.md         ← pointer; tells humans where the skill lives
docs/planning/interaction-design.md    ← pointer

Slug

The skills need a project slug for their name: frontmatter, so they don't collide with skills from other projects on the same machine.

Resolution order:

1. If package.json has a name, slugify it.
2. Else if a git remote exists, slugify the repo name.
3. Else ask the user. Default to the directory name.

Slug rule: lowercase, hyphenated, kebab-case, ASCII only. Example: SourdoughTracker → sourdough-tracker → skill sourdough-tracker-design-system.

design-system interview (placeholder pass)

Ask the user, in order, with sensible defaults:

1. Existing material? Brand assets, mood boards, screenshots, "make it look like Linear/Notion/Stripe", or nothing. If material exists, ingest it before asking the rest.
2. Color: brand color(s), neutral scale (warm/cool/true), dark mode (yes/no/system). Offer to generate accessible contrast pairs.
3. Typography: one family or two (display + body), size scale base and ratio, line-height policy.
4. Spacing: scale base (4px / 8px), key spacing tokens.
5. Radii: tight / medium / pillowy.
6. Shadows: flat / subtle / generous.
7. Visual motion: default duration, default easing.
8. Components: confirm vocabulary against ia.md.

Mark unanswered with <TBD: ...> so the return pass has a worklist.

Write phase — design-system

1. Write .claude/skills/<slug>-design-system/SKILL.md from templates/design-system/SKILL.md. Substitute the slug into the name: field and the project name into the description:.
2. Write .claude/skills/<slug>-design-system/tokens.ts from templates/design-system/tokens.ts. Fill in the values gathered in the interview; <TBD> for unanswered.
3. Write .claude/skills/<slug>-design-system/components.md from templates/design-system/components.md.
4. Write docs/planning/design-system.md from the pointer template — one paragraph saying where the skill lives.

interaction-design interview (placeholder pass)

Ask, in order:

1. Primary input: touch / mouse / keyboard / mixed. Primary, supported, not supported.
2. State surfaces: pick one pattern per action class.
3. Motion: minimal / restrained / expressive. prefers-reduced-motion always honored.
4. Breakpoints: count, primary design target.
5. i18n: locales planned, RTL, string-length budget.
6. Empty/loading/error/offline: one declared posture each.
7. Time formatting: relative threshold, absolute format.
8. Keyboard: global shortcuts, escape behavior.

Write phase — interaction-design

1. Write .claude/skills/<slug>-interaction-design/SKILL.md from templates/interaction-design/SKILL.md.
2. Write docs/planning/interaction-design.md pointer.

Re-entry

When the user returns to flesh this out fully:

• Expand the interviews above.
• Expand the SKILL.md and sidecar templates.
• Both skills are version-controlled in .claude/skills/ — re-running this phase shows the user a diff before overwriting.

The downstream contract is: composer-mocks reads the skills, not the planning pointer files. That contract does not change as the templates grow.

Hard rules even in placeholder mode

• Always produce both skills with sidecars. Mocks can't proceed without them.
• Always slug-namespace so projects on the same machine don't collide.
• Mark unknowns with <TBD: ...> rather than inventing — TBDs are the return-pass worklist.
• Don't pretend. If the user has nothing and no opinions, say so in the SKILL.md: "No design direction set; defaults applied. Revisit before mocks are committed."
• Tell the user what just happened. After write, print:

  Wrote two project skills:
    .claude/skills/<slug>-design-system/SKILL.md
    .claude/skills/<slug>-interaction-design/SKILL.md
  These auto-load whenever UI work is happening. Verify after restart
  with /agents (they should appear as project-local skills).