diff --git a/composer/skills/composer-mocks/SKILL.md b/composer/skills/composer-mocks/SKILL.md index 4a16041..32ff91b 100644 --- a/composer/skills/composer-mocks/SKILL.md +++ b/composer/skills/composer-mocks/SKILL.md @@ -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) diff --git a/composer/skills/composer/SKILL.md b/composer/skills/composer/SKILL.md index 4319655..809407e 100644 --- a/composer/skills/composer/SKILL.md +++ b/composer/skills/composer/SKILL.md @@ -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. diff --git a/composer/skills/ui-system/SKILL.md b/composer/skills/ui-system/SKILL.md index aa65f53..16a7b6b 100644 --- a/composer/skills/ui-system/SKILL.md +++ b/composer/skills/ui-system/SKILL.md @@ -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/-design-system/ and .claude/skills/-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/-design-system/ and .claude/skills/-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/-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. `` 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: • — - • 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/-design-system/SKILL.md` from `${CLAUDE_PLUGIN_ROOT}/templates/design-system/SKILL.md` — substitute slug, project name, and all interview answers. 2. `.claude/skills/-design-system/tokens.ts` from `${CLAUDE_PLUGIN_ROOT}/templates/design-system/tokens.ts` — fill in all values; `` for skipped phases. @@ -392,8 +138,8 @@ Wrote two project skills: .claude/skills/-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 (return-pass worklist): • @@ -401,7 +147,7 @@ Items still (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 `` 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. - **`` 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 diff --git a/composer/skills/ui-system/references/design-interview.md b/composer/skills/ui-system/references/design-interview.md new file mode 100644 index 0000000..6b10e6a --- /dev/null +++ b/composer/skills/ui-system/references/design-interview.md @@ -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 ``) 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. diff --git a/composer/skills/ui-system/references/inspiration-presets.md b/composer/skills/ui-system/references/inspiration-presets.md new file mode 100644 index 0000000..76be001 --- /dev/null +++ b/composer/skills/ui-system/references/inspiration-presets.md @@ -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. diff --git a/composer/skills/ui-system/references/interaction-interview.md b/composer/skills/ui-system/references/interaction-interview.md new file mode 100644 index 0000000..81d096b --- /dev/null +++ b/composer/skills/ui-system/references/interaction-interview.md @@ -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 +``) 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). diff --git a/symphony/skills/symphony-init/SKILL.md b/symphony/skills/symphony-init/SKILL.md index 231179a..0782cb1 100644 --- a/symphony/skills/symphony-init/SKILL.md +++ b/symphony/skills/symphony-init/SKILL.md @@ -1,13 +1,13 @@ --- 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 -You are running an interactive setup. The user wants Symphony configured for this repo -with as little hand-holding as possible. **Detect first, ask second.** Never ask a -question you can answer by probing the environment. +Run an interactive setup. The user wants Symphony configured for this repo with as +little hand-holding as possible. **Detect first, ask second.** Never ask a question +that can be answered by probing the environment. ## Detection pass (silent, no questions) diff --git a/symphony/skills/symphony/SKILL.md b/symphony/skills/symphony/SKILL.md index 91db0fd..9652a08 100644 --- a/symphony/skills/symphony/SKILL.md +++ b/symphony/skills/symphony/SKILL.md @@ -1,13 +1,13 @@ --- 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) -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 -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*. Symphony also stays open to **other trigger sources** (Discord channel, webhook,