movq/claude-plugins
2
0
Fork 0
Code Issues Pull Requests Actions Releases Activity

chore(composer,symphony): align skills with skill-development spec

Browse Source 
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>
This commit is contained in:
movq
2026-04-29 22:10:14 -05:00
parent 0cdbb1b4a4
commit 20acf3ae9b
8 changed files with 348 additions and 303 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
composer/skills/composer-mocks/SKILL.md
View File

@@ -1,15 +1,15 @@
--- ---
name: composer-mocks name: composer-mocks
description: Generate or revise high-fidelity JSX/TSX mocks for named user flows in a Composer project. Mocks reference the design system tokens and follow the patterns declared in interaction-design.md. After generation, runs a text feasibility audit — every visible string is categorized (static/computed/authored) and traced to source data, so mocks don't lie about features the app can't yet generate. Use when the user runs /composer-mock, when the composer skill reaches phase 7, or when the user asks to "mock the X flow". description: Generates or revises high-fidelity JSX/TSX mocks for named user flows in a Composer project. Mocks reference the design system tokens and follow the patterns declared in the interaction-design skill. After generation, runs a text feasibility audit — every visible string is categorized (static/computed/authored) and traced to source data, so mocks don't lie about features the app can't yet generate. This skill should be used when the user runs /composer-mock, when the composer skill reaches phase 7, or when the user asks to "mock the X flow", "generate a mock for X", "draft a UI for X flow", or "wireframe the X screen".
--- ---
# Composer mocks # Composer mocks
You generate **high-fidelity, non-functional** mocks in JSX/TSX. The Generate **high-fidelity, non-functional** mocks in JSX/TSX. The final
final application may end up React, React Native, SwiftUI, Flutter, or a application may end up React, React Native, SwiftUI, Flutter, or a plain
plain server-rendered template — JSX is just a fast, expressive way to server-rendered template — JSX is just a fast, expressive way to encode
encode layout, content, and component composition. The mock is a layout, content, and component composition. The mock is a **storyboard**,
**storyboard**, not a build artifact. not a build artifact.
## Prerequisites (hard checks) ## Prerequisites (hard checks)

4
composer/skills/composer/SKILL.md
View File

@@ -1,11 +1,11 @@
--- ---
name: composer name: composer
description: Discovery-phase orchestrator. State-aware skill that walks a user from "I want an app that…" to a tree of stories in their issue tracker, writing reviewable artifacts in docs/planning/ along the way. Use when the user runs /composer, /composer-status, /composer-review, or /composer-load — or asks to "start product discovery", "lay out a project", or "plan an app". For mock generation, the composer-mocks skill is invoked. For design/interaction system, ui-system is invoked. description: Discovery-phase orchestrator. State-aware skill that walks a user from "I want an app that…" to a tree of stories in their issue tracker, writing reviewable artifacts in docs/planning/ along the way. This skill should be used when the user runs /composer, /composer-status, /composer-review, or /composer-load — or asks to "start product discovery", "plan a new app", "lay out a project", "set up planning docs", or "scope out a product". For mock generation, the composer-mocks skill is invoked. For design/interaction system, ui-system is invoked.
--- ---
# Composer — orchestrator # Composer — orchestrator
You walk a user through product discovery, one phase at a time, producing Walk the user through product discovery, one phase at a time, producing
artifacts in `docs/planning/`. **Detect first, ask second.** Read what exists artifacts in `docs/planning/`. **Detect first, ask second.** Read what exists
before asking anything; resume at the first missing or stale phase. before asking anything; resume at the first missing or stale phase.

330
composer/skills/ui-system/SKILL.md
View File

@@ -1,11 +1,11 @@
--- ---
name: ui-system name: ui-system
description: 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. Use when the composer skill reaches phase 4 or 5, or when the user asks to "set up the design system", "specify interaction patterns", or "redo the 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 # UI system
You run a focused interview that produces two project-local skills: Run a focused interview that produces two project-local skills:
``` ```
.claude/skills/<slug>-design-system/ .claude/skills/<slug>-design-system/
@@ -43,11 +43,11 @@ Slug rule: lowercase kebab-case, ASCII only.
## Interview shape ## Interview shape
Two parts, **sequential**: design system first (visual), then Two parts, **sequential**: design system first (visual), then interaction
interaction design (behavioral). Don't interleave — they're different design (behavioral). Don't interleave — they're different conversations
conversations and the visual posture often informs interaction choices. and the visual posture often informs interaction choices.
Each phase: For each phase:
1. State what's being decided and why it matters (one line). 1. State what's being decided and why it matters (one line).
2. Show the default if there is one. 2. Show the default if there is one.
3. Ask the question. Batch related questions when they cluster naturally. 3. Ask the question. Batch related questions when they cluster naturally.
@@ -60,8 +60,6 @@ The user can answer **`default`** or **`skip`** at any phase:
Never invent on the user's behalf. `<TBD>` is a worklist, not a failure. Never invent on the user's behalf. `<TBD>` is a worklist, not a failure.
---
## Phase 0 — Material ingestion (silent) ## Phase 0 — Material ingestion (silent)
Before asking anything, scan for material the user already has. Read Before asking anything, scan for material the user already has. Read
@@ -78,304 +76,52 @@ without asking; surface findings before the first question.
| `README.md`, `BRANDING.md`, `STYLE.md` | style notes the user wrote | | `README.md`, `BRANDING.md`, `STYLE.md` | style notes the user wrote |
| Existing `docs/planning/concept.md` | platform hint (web/mobile/native) | | Existing `docs/planning/concept.md` | platform hint (web/mobile/native) |
Then before the interview opens: Before the interview opens, summarize:
``` ```
Material I found and will use: Material I found and will use:
• <thing> — <how it'll inform the interview> • <thing> — <how it'll inform the interview>
• <thing>
Not found (will ask): brand color, type family, motion posture. Not found (will ask): brand color, type family, motion posture.
``` ```
If the user has named a reference like *"make it look like Linear"* in 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 a previous Composer phase, surface it here and apply the matching preset
preset (see "Reference banks" below). (see `references/inspiration-presets.md`).
--- ## Part 1 — Design system
# Part 1 — Design system Run phases **D1 through D11** as specified in `references/design-interview.md`.
## D1 — Visual posture (one paragraph) 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).
The north star sentence for visual decisions. Don't ask for paragraphs; Read the reference for each phase before asking. Defaults and decision
ask for adjectives and assemble. guidance live there.
``` ## Part 2 — Interaction design
Three or four words that describe how this should feel.
Examples: "quiet, dense, monochrome, one accent" / "playful,
generous, expressive type" / "clinical, neutral, accessibility-forward".
```
Compose into a single sentence; show; accept. Run phases **I1 through I11** as specified in `references/interaction-interview.md`.
## D2 — Color 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).
Batch as a single phase with sub-questions; tight loop. Skip I10 entirely if I1's primary input is not touch.
**D2.1 Brand primary.** If material gave a color, propose it. Else:
```
Pick a brand primary. Either name a hex, name a color
("warm orange", "deep teal"), or name a reference ("Linear's purple",
"Stripe's indigo"). I'll generate the variants from there.
```
**D2.2 Brand secondary.** Optional. `default` = none.
**D2.3 Neutral tone.** Warm / cool / true. One question.
```
For grays, do they feel slightly tan (warm), slightly blue (cool),
or truly neutral (true)? Default: cool.
```
**D2.4 Generate the neutral scale.** Compute 50–950 from the chosen tone
and brand contrast targets. Show the user; offer `default` or "redo with
warmer/cooler/more contrast".
**D2.5 Semantic colors.** Success / warning / error / info. Show defaults
that contrast against both light and dark backgrounds; user accepts or
overrides one at a time.
**D2.6 Dark mode.** yes / no / system-following. Default: system. If yes,
generate the dark token mapping (invert + adjust saturation per token
class) and show.
**D2.7 Accessibility check.** Compute contrast ratios between primary +
neutral pairs. Flag anything below 4.5:1 for body text or 3:1 for UI.
Don't silently accept failures — surface and confirm or adjust.
## D3 — Typography
**D3.1 One family or two?** Default: one.
**D3.2 Family choice.** If user has no preference, offer presets:
- *Modern sans*: Inter (free, broad weights)
- *Humanist*: Source Sans 3 / IBM Plex Sans
- *System stack*: native to OS (free, no load)
- *Editorial*: Inter + Fraunces (display)
- *Technical*: IBM Plex Sans + IBM Plex Mono
**D3.3 Scale base.** 14, 15, 16. Default: 16 (web), 17 (iOS native), 14 (compact dashboards).
**D3.4 Scale ratio.** 1.125 (subtle), 1.2, 1.25 (default), 1.333 (dramatic), 1.5 (display-heavy).
**D3.5 Line-height policy.**
- Display: 1.1–1.2 (tight)
- Body: 1.5 (normal)
- Long-form prose: 1.7 (relaxed)
Defaults usually fine; user can override one of three.
## D4 — Spacing
**D4.1 Base unit.** 4 (default — finer control) or 8 (rougher cadence; iOS native often).
**D4.2 Scale.** Use the standard 12-step (0, 0.5, 1, 1.5, 2, 3, 4, 6, 8, 12, 16, 24) — almost always accepted as `default`.
## D5 — Radii
**D5.1 Posture.** sharp (0–4) / tight (4–8) / medium (8–16) / pillowy (16+) / mixed.
**D5.2 Generate sm/md/lg/pill/full.** Show; accept or tweak one.
## D6 — Shadows & elevation
**D6.1 Posture.** flat (none) / subtle / generous.
**D6.2 Scale.** xs/sm/md/lg/xl. Generated from posture; show; accept.
## D7 — Density
**D7.1 Default density.** comfortable (default; web app) / cozy / compact (data-heavy dashboard).
This drives component padding tokens — important enough to ask, easy to forget otherwise.
## D8 — Visual motion
**D8.1 Default duration.** fast (150ms), default (250ms), slow (400ms). Default: default.
**D8.2 Default easing.** standard / accel / decel / custom. Default: standard.
Behavioral motion (when things animate) lives in interaction design.
## D9 — Components
Read the entity vocabulary from `ia.md`. Confirm the standard set
(Button, Input, Card, Surface) and ask for project-specific
additions found in IA.
For each project-specific component, ask: variants? states? anatomy?
Default to "standard variants only" if user is unsure — better to add
later than over-spec now.
## D10 — Theme variants (skip by default)
Multi-brand / tenant theming usually no for v1. Default: skip.
## D11 — Accessibility tokens
**D11.1 Focus ring.** Style (solid / double / inner-outer) and color (brand / accent / outline-default). Default: solid 2px brand at 60% opacity.
**D11.2 Contrast targets.** Confirm WCAG AA (4.5:1 text, 3:1 UI). AAA optional. Default: AA.
---
# Part 2 — Interaction design
## I1 — Input model
**I1.1 Primary input.** touch (mobile/tablet) / mouse / keyboard / mixed.
Often determined by platform from `concept.md` — confirm rather than ask cold.
**I1.2 Supported inputs.** Which secondaries must work; which are not in scope.
**I1.3 Voice / switch / assistive.** Defer unless `users.md` has an actor that needs it.
## I2 — State surface declarations
The most important phase. For each action class, pick one pattern. Walk
through them in this order:
| Action class | Common picks | Default |
|---|---|---|
| Quick edit (single field) | inline edit / popover / drawer | inline edit |
| Multi-field create | drawer / modal / full-page route | drawer (web), modal (native) |
| Multi-field edit | drawer / modal / full-page route | same as create |
| Confirm destructive | modal | modal (always — non-negotiable) |
| Settings / configuration | full-page route | full-page route |
| Top-level navigation | sidebar / tab bar / header nav | tab bar (mobile), sidebar (desktop) |
| Detail-from-list | full route / side panel / drawer | full route |
| Filtering / sorting | inline controls / popover / drawer | inline (small set), drawer (large set) |
| Search | header search / command palette / page | header search |
For each, show the default and the alternatives. User confirms or picks.
## I3 — Motion posture
**I3.1 Posture.** minimal / restrained / expressive.
**I3.2 Animation triggers.** For each, yes/no/conditional:
- Page/route transitions
- List item enter/exit
- Modal/drawer open/close
- State changes (toggle, expand)
- Loading→loaded transitions
Defaults from the posture choice — show; accept.
**I3.3 Reduced motion fallbacks.** Confirm `prefers-reduced-motion` is
honored (always yes; this is policy, not preference).
## I4 — Breakpoints
**I4.1 Count.** 2 (mobile / desktop) / 3 (mobile / tablet / desktop) / 4 (with large desktop) / fluid.
**I4.2 Values.** Defaults: 640 / 768 / 1024 / 1280. Tweakable.
**I4.3 Primary target.** mobile-first / desktop-first / fluid. Determined by platform.
## I5 — i18n
**I5.1 Locales at launch.** Default: just English (`en` or `en-US`).
**I5.2 RTL support.** yes / no / planned. Default: no in v1.
**I5.3 Pluralization.** ICU MessageFormat / library / manual. Default: ICU MessageFormat (industry standard).
**I5.4 String length budget.** Default: assume +30% over English for de/fr translations. Always declared.
## I6 — State postures
Four sub-decisions; one declared posture each.
**I6.1 Empty state.**
- Visual: icon + heading + body + CTA / heading + body / heading only.
- Tone: encouraging / neutral / matter-of-fact.
- CTA: present always / present when actionable / never.
**I6.2 Loading state.**
- Default: skeleton / spinner / blocking. Pick one default; assign exceptions.
- Threshold for showing loading at all: 200ms (default) / 300ms / immediate.
**I6.3 Error state.**
- Surface: inline (default) / toast / dialog. By severity class.
- Recovery: retry / clear path forward / report.
- Copy tone: plain language always; what happened + what to do next.
**I6.4 Offline state.**
- Behavior: full subset works / banner only / "go online to continue".
- Sync: queue + flush on reconnect / fail loudly / not in v1.
## I7 — Time formatting
**I7.1 Relative-time threshold.** Within `<7 days>` / `<30 days>` / `<24 hours>` / never. Default: 7 days.
**I7.2 Absolute format.** `MMM d, yyyy h:mm a` / ISO / locale-aware. Default: locale-aware via `Intl.DateTimeFormat`.
**I7.3 Time zones.** user-local / fixed (which?) / configurable. Default: user-local.
## I8 — Keyboard
**I8.1 Global shortcuts.** Y/N for v1. If yes, list them; if no, mark "deferred to vN".
**I8.2 Modal escape.** Always yes; confirm.
**I8.3 Focus trap in modal.** Always yes; confirm. Restore on close.
**I8.4 Form submit.** Enter submits / Cmd+Enter submits / explicit only. Default: Enter submits.
**I8.5 List navigation.** Arrow keys yes/no. Default: no in v1 unless lists are central.
## I9 — Optimistic updates & error recovery
**I9.1 Default posture.**
- Optimistic with rollback (default for most actions — feels fast)
- Pessimistic (default for destructive or money-related actions)
- Mixed (most actions optimistic; some classes pessimistic)
**I9.2 Rollback strategy.** Toast + revert / silent revert / dialog. Default: toast + revert.
**I9.3 Conflict resolution.** Last-write-wins / show conflict UI / append. Default depends on platform.
## I10 — Gestures (touch only)
Skip this phase if I1.1 didn't include touch.
**I10.1 Swipe actions on rows.** Y/N. If yes: which actions, which directions.
**I10.2 Long-press menu.** Y/N. Default: yes (iOS/Android conventional).
**I10.3 Pull-to-refresh.** Y/N for list views.
## I11 — Focus management
**I11.1 After modal close.** Restore previous focus (default — non-negotiable for a11y).
**I11.2 After route change.** Heading focus (default) / container focus / no change.
**I11.3 After form error.** Focus first error field (default).
---
## Reference banks ## Reference banks
When the user names a reference ("like Linear", "like Notion"), apply When the user says "make it look like Linear / Notion / Stripe / etc.",
these presets as starting points — user still confirms each value. apply the matching preset from `references/inspiration-presets.md` as a
starting point. The user still confirms each value — presets seed the
| Reference | Visual posture | Color tone | Type | Density | Motion | Radii | conversation, they don't replace it. For "make it look exotic / brutalist
|---|---|---|---|---|---|---| / playful", ask for reference URLs and synthesize a posture sentence
| **Linear** | quiet, dense, monochrome with one purple accent | cool neutral | Inter | compact | restrained, fast | tight | rather than picking a preset.
| **Notion** | minimal, generous spacing, friendly | warm-leaning true neutral | Inter / system | comfortable | minimal | medium |
| **Stripe** | clean, technical, indigo accent | cool neutral | Camphor / system | comfortable | restrained | medium |
| **GitHub** | utilitarian, dense, clear hierarchy | cool true neutral | -apple-system stack | compact | minimal | tight |
| **Vercel** | sharp, monochrome, contrasty | true neutral, almost B&W | Geist / Inter | comfortable | restrained, fast | tight |
| **Apple HIG** | spacious, soft, system-native | warm-cool mix per platform | SF Pro | cozy | expressive | medium |
| **Material 3** | adaptive, expressive, dynamic color | tone-based dynamic | Roboto / Plus Jakarta | comfortable | expressive | pillowy |
For "make it look exotic / brutalist / playful / etc.", branch
cleanly: ask for two or three reference URLs the user has in mind,
and reflect them back as a posture sentence rather than picking presets.
## Write phase ## Write phase
After the interview ends, write all six files in one batch: 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. 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. 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.
@@ -392,8 +138,8 @@ Wrote two project skills:
.claude/skills/<slug>-interaction-design/ (SKILL.md) .claude/skills/<slug>-interaction-design/ (SKILL.md)
These auto-load whenever UI work is happening. They should be available These auto-load whenever UI work is happening. They should be available
immediately in this session; if you're starting a new session in this immediately in this session; if the user is starting a new session in
repo, they'll load on the first UI-related prompt. this repo, they'll load on the first UI-related prompt.
Items still <TBD> (return-pass worklist): Items still <TBD> (return-pass worklist):
• <list any phases that were skipped or had unanswered questions> • <list any phases that were skipped or had unanswered questions>
@@ -401,7 +147,7 @@ Items still <TBD> (return-pass worklist):
## Re-entry ## Re-entry
Re-running the skill on a project that already has the artifacts: 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. 1. Read both existing SKILL.md files plus tokens.ts and components.md.
2. List what's currently set; mark `<TBD>` items prominently. 2. List what's currently set; mark `<TBD>` items prominently.
@@ -415,6 +161,14 @@ Re-running the skill on a project that already has the artifacts:
- **Always slug-namespace** so projects on the same machine don't collide. - **Always slug-namespace** so projects on the same machine don't collide.
- **`<TBD: ...>` rather than invent.** TBDs are the return-pass worklist. - **`<TBD: ...>` rather than invent.** TBDs are the return-pass worklist.
- **Verify a11y contrast** before writing color tokens. Don't silently accept failures. - **Verify a11y contrast** before writing color tokens. Don't silently accept failures.
- **Honor `prefers-reduced-motion` is policy, not opinion.** Always declare it as honored. - **Honor `prefers-reduced-motion`** is policy, not opinion. Always declared as honored.
- **Confirm before overwriting** existing skill files on re-entry. - **Confirm before overwriting** existing skill files on re-entry.
- **Tell the user what was written and where**, plus how to verify the skills load. - **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

129
composer/skills/ui-system/references/design-interview.md Normal file
View File

@@ -0,0 +1,129 @@
# Design system interview — full phase reference
Detailed phases for Part 1 of the ui-system interview. Read this when running
the design-system interview; it expands the phase summaries in SKILL.md.
Each phase: state what's being decided, show the default if there is one, ask
the question(s), confirm the answer back, move on. The user can reply
`default` (accept) or `skip` (mark `<TBD: ...>`) at any phase.
## D1 — Visual posture (one paragraph)
The north star sentence for visual decisions. Don't ask for paragraphs;
ask for adjectives and assemble.
```
Three or four words that describe how this should feel.
Examples: "quiet, dense, monochrome, one accent" / "playful,
generous, expressive type" / "clinical, neutral, accessibility-forward".
```
Compose into a single sentence; show; accept.
## D2 — Color
Batch as a single phase with sub-questions; tight loop.
**D2.1 Brand primary.** If material gave a color, propose it. Else:
```
Pick a brand primary. Either name a hex, name a color
("warm orange", "deep teal"), or name a reference ("Linear's purple",
"Stripe's indigo"). I'll generate the variants from there.
```
**D2.2 Brand secondary.** Optional. `default` = none.
**D2.3 Neutral tone.** Warm / cool / true. One question.
```
For grays, do they feel slightly tan (warm), slightly blue (cool),
or truly neutral (true)? Default: cool.
```
**D2.4 Generate the neutral scale.** Compute 50–950 from the chosen tone
and brand contrast targets. Show the user; offer `default` or "redo with
warmer/cooler/more contrast".
**D2.5 Semantic colors.** Success / warning / error / info. Show defaults
that contrast against both light and dark backgrounds; user accepts or
overrides one at a time.
**D2.6 Dark mode.** yes / no / system-following. Default: system. If yes,
generate the dark token mapping (invert + adjust saturation per token
class) and show.
**D2.7 Accessibility check.** Compute contrast ratios between primary +
neutral pairs. Flag anything below 4.5:1 for body text or 3:1 for UI.
Don't silently accept failures — surface and confirm or adjust.
## D3 — Typography
**D3.1 One family or two?** Default: one.
**D3.2 Family choice.** If user has no preference, offer presets:
- *Modern sans*: Inter (free, broad weights)
- *Humanist*: Source Sans 3 / IBM Plex Sans
- *System stack*: native to OS (free, no load)
- *Editorial*: Inter + Fraunces (display)
- *Technical*: IBM Plex Sans + IBM Plex Mono
**D3.3 Scale base.** 14, 15, 16. Default: 16 (web), 17 (iOS native), 14 (compact dashboards).
**D3.4 Scale ratio.** 1.125 (subtle), 1.2, 1.25 (default), 1.333 (dramatic), 1.5 (display-heavy).
**D3.5 Line-height policy.**
- Display: 1.1–1.2 (tight)
- Body: 1.5 (normal)
- Long-form prose: 1.7 (relaxed)
Defaults usually fine; user can override one of three.
## D4 — Spacing
**D4.1 Base unit.** 4 (default — finer control) or 8 (rougher cadence; iOS native often).
**D4.2 Scale.** Use the standard 12-step (0, 0.5, 1, 1.5, 2, 3, 4, 6, 8, 12, 16, 24) — almost always accepted as `default`.
## D5 — Radii
**D5.1 Posture.** sharp (0–4) / tight (4–8) / medium (8–16) / pillowy (16+) / mixed.
**D5.2 Generate sm/md/lg/pill/full.** Show; accept or tweak one.
## D6 — Shadows & elevation
**D6.1 Posture.** flat (none) / subtle / generous.
**D6.2 Scale.** xs/sm/md/lg/xl. Generated from posture; show; accept.
## D7 — Density
**D7.1 Default density.** comfortable (default; web app) / cozy / compact (data-heavy dashboard).
This drives component padding tokens — important enough to ask, easy to forget otherwise.
## D8 — Visual motion
**D8.1 Default duration.** fast (150ms), default (250ms), slow (400ms). Default: default.
**D8.2 Default easing.** standard / accel / decel / custom. Default: standard.
Behavioral motion (when things animate) lives in the interaction interview, not here.
## D9 — Components
Read the entity vocabulary from `ia.md`. Confirm the standard set
(Button, Input, Card, Surface) and ask for project-specific additions found in IA.
For each project-specific component, ask: variants? states? anatomy?
Default to "standard variants only" if user is unsure — better to add
later than over-spec now.
## D10 — Theme variants (skip by default)
Multi-brand / tenant theming usually no for v1. Default: skip.
## D11 — Accessibility tokens
**D11.1 Focus ring.** Style (solid / double / inner-outer) and color (brand / accent / outline-default). Default: solid 2px brand at 60% opacity.
**D11.2 Contrast targets.** Confirm WCAG AA (4.5:1 text, 3:1 UI). AAA optional. Default: AA.

21
composer/skills/ui-system/references/inspiration-presets.md Normal file
View File

@@ -0,0 +1,21 @@
# Inspiration presets
When the user names a reference ("like Linear", "like Notion"), apply these
presets as starting points. The user still confirms each value — presets
seed the conversation, they don't replace it.
| Reference | Visual posture | Color tone | Type | Density | Motion | Radii |
|---|---|---|---|---|---|---|
| **Linear** | quiet, dense, monochrome with one purple accent | cool neutral | Inter | compact | restrained, fast | tight |
| **Notion** | minimal, generous spacing, friendly | warm-leaning true neutral| Inter / system | comfortable | minimal | medium |
| **Stripe** | clean, technical, indigo accent | cool neutral | Camphor / system | comfortable | restrained | medium |
| **GitHub** | utilitarian, dense, clear hierarchy | cool true neutral | -apple-system stack | compact | minimal | tight |
| **Vercel** | sharp, monochrome, contrasty | true neutral, almost B&W | Geist / Inter | comfortable | restrained, fast | tight |
| **Apple HIG** | spacious, soft, system-native | warm-cool mix per platform| SF Pro | cozy | expressive | medium |
| **Material 3** | adaptive, expressive, dynamic color | tone-based dynamic | Roboto / Plus Jakarta | comfortable | expressive | pillowy |
For "make it look exotic / brutalist / playful / etc.", branch cleanly: ask
for two or three reference URLs the user has in mind, and reflect them back
as a posture sentence rather than picking presets. Don't invent a preset —
the value of this table is that the rows are well-known, recognizable
products, not vibes.

141
composer/skills/ui-system/references/interaction-interview.md Normal file
View File

@@ -0,0 +1,141 @@
# Interaction design interview — full phase reference
Detailed phases for Part 2 of the ui-system interview. Read this when running
the interaction-design interview; it expands the phase summaries in SKILL.md.
Each phase: state what's being decided, show the default, ask the question,
confirm, move on. The user can reply `default` (accept) or `skip` (mark
`<TBD: ...>`) at any phase.
## I1 — Input model
**I1.1 Primary input.** touch (mobile/tablet) / mouse / keyboard / mixed.
Often determined by platform from `concept.md` — confirm rather than ask cold.
**I1.2 Supported inputs.** Which secondaries must work; which are not in scope.
**I1.3 Voice / switch / assistive.** Defer unless `users.md` has an actor that needs it.
## I2 — State surface declarations
The most important phase. For each action class, pick one pattern. Walk
through them in this order:
| Action class | Common picks | Default |
|---|---|---|
| Quick edit (single field) | inline edit / popover / drawer | inline edit |
| Multi-field create | drawer / modal / full-page route | drawer (web), modal (native) |
| Multi-field edit | drawer / modal / full-page route | same as create |
| Confirm destructive | modal | modal (always — non-negotiable) |
| Settings / configuration | full-page route | full-page route |
| Top-level navigation | sidebar / tab bar / header nav | tab bar (mobile), sidebar (desktop) |
| Detail-from-list | full route / side panel / drawer | full route |
| Filtering / sorting | inline controls / popover / drawer | inline (small set), drawer (large set) |
| Search | header search / command palette / page | header search |
For each, show the default and the alternatives. User confirms or picks.
## I3 — Motion posture
**I3.1 Posture.** minimal / restrained / expressive.
**I3.2 Animation triggers.** For each, yes/no/conditional:
- Page/route transitions
- List item enter/exit
- Modal/drawer open/close
- State changes (toggle, expand)
- Loading→loaded transitions
Defaults from the posture choice — show; accept.
**I3.3 Reduced motion fallbacks.** Confirm `prefers-reduced-motion` is
honored (always yes; this is policy, not preference).
## I4 — Breakpoints
**I4.1 Count.** 2 (mobile / desktop) / 3 (mobile / tablet / desktop) / 4 (with large desktop) / fluid.
**I4.2 Values.** Defaults: 640 / 768 / 1024 / 1280. Tweakable.
**I4.3 Primary target.** mobile-first / desktop-first / fluid. Determined by platform.
## I5 — i18n
**I5.1 Locales at launch.** Default: just English (`en` or `en-US`).
**I5.2 RTL support.** yes / no / planned. Default: no in v1.
**I5.3 Pluralization.** ICU MessageFormat / library / manual. Default: ICU MessageFormat (industry standard).
**I5.4 String length budget.** Default: assume +30% over English for de/fr translations. Always declared.
## I6 — State postures
Four sub-decisions; one declared posture each.
**I6.1 Empty state.**
- Visual: icon + heading + body + CTA / heading + body / heading only.
- Tone: encouraging / neutral / matter-of-fact.
- CTA: present always / present when actionable / never.
**I6.2 Loading state.**
- Default: skeleton / spinner / blocking. Pick one default; assign exceptions.
- Threshold for showing loading at all: 200ms (default) / 300ms / immediate.
**I6.3 Error state.**
- Surface: inline (default) / toast / dialog. By severity class.
- Recovery: retry / clear path forward / report.
- Copy tone: plain language always; what happened + what to do next.
**I6.4 Offline state.**
- Behavior: full subset works / banner only / "go online to continue".
- Sync: queue + flush on reconnect / fail loudly / not in v1.
## I7 — Time formatting
**I7.1 Relative-time threshold.** Within `<7 days>` / `<30 days>` / `<24 hours>` / never. Default: 7 days.
**I7.2 Absolute format.** `MMM d, yyyy h:mm a` / ISO / locale-aware. Default: locale-aware via `Intl.DateTimeFormat`.
**I7.3 Time zones.** user-local / fixed (which?) / configurable. Default: user-local.
## I8 — Keyboard
**I8.1 Global shortcuts.** Y/N for v1. If yes, list them; if no, mark "deferred to vN".
**I8.2 Modal escape.** Always yes; confirm.
**I8.3 Focus trap in modal.** Always yes; confirm. Restore on close.
**I8.4 Form submit.** Enter submits / Cmd+Enter submits / explicit only. Default: Enter submits.
**I8.5 List navigation.** Arrow keys yes/no. Default: no in v1 unless lists are central.
## I9 — Optimistic updates & error recovery
**I9.1 Default posture.**
- Optimistic with rollback (default for most actions — feels fast)
- Pessimistic (default for destructive or money-related actions)
- Mixed (most actions optimistic; some classes pessimistic)
**I9.2 Rollback strategy.** Toast + revert / silent revert / dialog. Default: toast + revert.
**I9.3 Conflict resolution.** Last-write-wins / show conflict UI / append. Default depends on platform.
## I10 — Gestures (touch only)
Skip this phase if I1.1 didn't include touch.
**I10.1 Swipe actions on rows.** Y/N. If yes: which actions, which directions.
**I10.2 Long-press menu.** Y/N. Default: yes (iOS/Android conventional).
**I10.3 Pull-to-refresh.** Y/N for list views.
## I11 — Focus management
**I11.1 After modal close.** Restore previous focus (default — non-negotiable for a11y).
**I11.2 After route change.** Heading focus (default) / container focus / no change.
**I11.3 After form error.** Focus first error field (default).

8
symphony/skills/symphony-init/SKILL.md
View File

@@ -1,13 +1,13 @@
--- ---
name: symphony-init name: symphony-init
description: First-time setup for the Symphony plugin in a project. Detects the issue tracker, writes a tracker integration section into the project's CLAUDE.md, drops a starter WORKFLOW.md, and optionally schedules the orchestrator tick. Use when the user runs /symphony-init or asks to "set up Symphony" / "configure Symphony for this repo". Idempotent — re-running detects existing config and offers updates rather than overwriting. description: First-time setup for the Symphony plugin in a project. Detects the issue tracker, writes a tracker integration section into the project's CLAUDE.md, drops a starter WORKFLOW.md, and optionally schedules the orchestrator tick. This skill should be used when the user runs /symphony-init or asks to "set up Symphony", "configure Symphony for this repo", "initialize Symphony", or "wire up the issue tracker for Symphony". Idempotent — re-running detects existing config and offers updates rather than overwriting.
--- ---
# Symphony — project initialization # Symphony — project initialization
You are running an interactive setup. The user wants Symphony configured for this repo Run an interactive setup. The user wants Symphony configured for this repo with as
with as little hand-holding as possible. **Detect first, ask second.** Never ask a little hand-holding as possible. **Detect first, ask second.** Never ask a question
question you can answer by probing the environment. that can be answered by probing the environment.
## Detection pass (silent, no questions) ## Detection pass (silent, no questions)

6
symphony/skills/symphony/SKILL.md
View File

@@ -1,13 +1,13 @@
--- ---
name: symphony name: symphony
description: Orchestrator skill for the Symphony plugin. Runs one tick — loads WORKFLOW.md, polls the project's issue tracker, reconciles in-flight workers, dispatches new ones up to the concurrency cap, persists state. Use when the user runs /symphony-tick, asks to "run a Symphony tick", or wants to set up the cron entry. Not for one-off issue work — that's the symphony-worker agent. description: Orchestrator skill for the Symphony plugin. Runs one tick — loads WORKFLOW.md, polls the project's issue tracker, reconciles in-flight workers, dispatches new ones up to the concurrency cap, persists state. This skill should be used when the user runs /symphony-tick, asks to "run a Symphony tick", "dispatch issues", "poll the tracker", or wants to set up the orchestrator schedule. Not for one-off issue work — that's the symphony-worker agent.
--- ---
# Symphony orchestrator (one tick) # Symphony orchestrator (one tick)
You are the dispatcher. Each invocation runs **one** poll-and-dispatch pass and returns. Act as the dispatcher. Each invocation runs **one** poll-and-dispatch pass and returns.
The orchestrator runs in a long-lived session — `/schedule` fires ticks within the The orchestrator runs in a long-lived session — `/schedule` fires ticks within the
running session rather than cold-starting. Tasks you spawn in tick N stay visible to running session rather than cold-starting. Tasks spawned in tick N stay visible to
`TaskList` in tick N+1 *within the same session*. `TaskList` in tick N+1 *within the same session*.
Symphony also stays open to **other trigger sources** (Discord channel, webhook, Symphony also stays open to **other trigger sources** (Discord channel, webhook,