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>
This commit is contained in:
movq
@@ -1,15 +1,15 @@
|
||||
---
|
||||
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
|
||||
|
||||
You generate **high-fidelity, non-functional** mocks in JSX/TSX. The
|
||||
final application may end up React, React Native, SwiftUI, Flutter, or a
|
||||
plain server-rendered template — JSX is just a fast, expressive way to
|
||||
encode layout, content, and component composition. The mock is a
|
||||
**storyboard**, not a build artifact.
|
||||
Generate **high-fidelity, non-functional** mocks in JSX/TSX. The final
|
||||
application may end up React, React Native, SwiftUI, Flutter, or a plain
|
||||
server-rendered template — JSX is just a fast, expressive way to encode
|
||||
layout, content, and component composition. The mock is a **storyboard**,
|
||||
not a build artifact.
|
||||
|
||||
## Prerequisites (hard checks)
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
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
|
||||
|
||||
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
|
||||
before asking anything; resume at the first missing or stale phase.
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
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
|
||||
|
||||
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/
|
||||
@@ -43,11 +43,11 @@ Slug rule: lowercase kebab-case, ASCII only.
|
||||
|
||||
## 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.
|
||||
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.
|
||||
|
||||
Each phase:
|
||||
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.
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Material ingestion (silent)
|
||||
|
||||
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 |
|
||||
| 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:
|
||||
• <thing> — <how it'll inform the interview>
|
||||
• <thing>
|
||||
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 "Reference banks" below).
|
||||
a previous Composer phase, surface it here and apply the matching preset
|
||||
(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;
|
||||
ask for adjectives and assemble.
|
||||
Read the reference for each phase before asking. Defaults and decision
|
||||
guidance live there.
|
||||
|
||||
```
|
||||
Three or four words that describe how this should feel.
|
||||
Examples: "quiet, dense, monochrome, one accent" / "playful,
|
||||
generous, expressive type" / "clinical, neutral, accessibility-forward".
|
||||
```
|
||||
## Part 2 — Interaction design
|
||||
|
||||
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.
|
||||
|
||||
**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).
|
||||
|
||||
---
|
||||
Skip I10 entirely if I1's primary input is not touch.
|
||||
|
||||
## Reference banks
|
||||
|
||||
When the user names a reference ("like Linear", "like Notion"), apply
|
||||
these presets as starting points — user still confirms each value.
|
||||
|
||||
| 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.
|
||||
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 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.
|
||||
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)
|
||||
|
||||
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
|
||||
repo, they'll load on the first UI-related prompt.
|
||||
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>
|
||||
@@ -401,7 +147,7 @@ Items still <TBD> (return-pass worklist):
|
||||
|
||||
## 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.
|
||||
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.
|
||||
- **`<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 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.
|
||||
- **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
129
composer/skills/ui-system/references/design-interview.md
Normal 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
21
composer/skills/ui-system/references/inspiration-presets.md
Normal 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
141
composer/skills/ui-system/references/interaction-interview.md
Normal 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).
|
||||
Reference in New Issue
Block a user