@staff0rd/assist 0.384.2 → 0.385.0

package/README.md

@@ -64,6 +64,7 @@ After installation, the `assist` command will be available globally. You can als
 - `/subtask <text>` - Add a sub-task to the backlog item this session is working on (errors if there is no current item) by calling `assist backlog add-subtask`
 - `/strip-comments` - Enforce self-documenting code: declare the comment policy in CLAUDE.md if absent, then strip redundant comments, commented-out code, and section banners from tracked source files (functional directives and genuine workaround comments are preserved); edits are left unstaged
 - `/sync` - Sync commands and settings to ~/.claude
+- `/design <prompt>` - Adopt the vendored design system prompt (`~/.claude/system-prompt.md`) and its design skills (`~/.claude/skills/`, both installed by `assist sync`) as context, then apply that design guidance to `<prompt>`
 - `/test-cover` - Incrementally increase test coverage by identifying and testing uncovered files
 - `/test-review` - Review existing tests for quality, coverage gaps, and adherence to conventions
 - `/inspect` - Run .NET code inspections on changed files
@@ -90,7 +91,7 @@ After installation, the `assist` command will be available globally. You can als
 - `assist init` - Initialize project with VS Code and verify configurations
 - `assist new vite` - Initialize a new Vite React TypeScript project
 - `assist new cli` - Initialize a new tsup CLI project
-- `assist sync` - Copy command files to `~/.claude/commands`
+- `assist sync` - Copy command files to `~/.claude/commands`, sync `settings.json` and `CLAUDE.md`, and install the design assets — `claude/system-prompt.md` to `~/.claude/system-prompt.md` and `claude/skills/*` into `~/.claude/skills` (existing files in that directory are preserved)
 - `assist commit status` - Show git status and diff
 - `assist commit <message>` - Commit staged changes with validation
 - `assist commit <message> [files...]` - Stage files and create a git commit with validation
@@ -285,6 +286,8 @@ Backlog item ids are written and displayed in an `a`-prefixed form (e.g. item 55
 - `assist daemon restart` - Restart the sessions daemon, resuming previously running claude sessions
 - `assist daemon drain` - Remove all sessions from the local daemon for a clean slate (does not affect the Windows daemon)
 
+The sessions topnav has a **Design** dropdown: submitting a prompt launches an interactive `claude` session with the vendored design system prompt appended via `--append-system-prompt` (so the 647-line prompt stays out of the visible conversation) and the prompt sent as the first message; submitting an empty prompt opens a design-configured session with no initial message.
+
 Web sessions are owned by a long-lived daemon process, not the web server: the server is a thin client that relays WebSocket traffic to the daemon over a local IPC socket (unix domain socket at `~/.assist/daemon/daemon.sock`; named pipe `\\.\pipe\assist-sessions-daemon` on Windows). Restarting the web server leaves sessions running with scrollback intact. The daemon logs to `~/.assist/daemon/daemon.log` (timestamped lines tagged with the daemon's pid, including why it spawned and which sessions it restored) and auto-exits once no sessions remain and no client has been connected for 60 seconds (it is respawned on demand by the web server). Daemon spawning is arbitrated by an `O_EXCL` lockfile so racing clients start at most one daemon; sessions are only restored after the daemon owns the IPC socket, and a daemon that loses ownership of `daemon.pid` shuts down its sessions and exits rather than running orphaned.
 
 From WSL, the selector can also surface and drive Windows-host repos (requires `assist` installed on the Windows host). Config keys:

package/claude/commands/design.md

@@ -0,0 +1,24 @@
+---
+description: Adopt the vendored design system prompt and apply it to a design task
+allowed_args: "<design prompt>"
+---
+
+You are being asked to act as an expert designer for the remainder of this task. The design guidance lives in files synced to `~/.claude` by `assist sync`.
+
+## Step 1: Load the design system prompt
+
+Read `~/.claude/system-prompt.md` in full. This is a 647-line design system prompt that defines your identity, workflow, and standards as a designer. Adopt it as your operating context for this task — its instructions take precedence over your default behaviour for the design work that follows.
+
+If the file is missing, tell the user to run `assist sync` first and stop.
+
+## Step 2: Note the available skills
+
+The design skills referenced by the system prompt (`discovery-questions`, `frontend-aesthetic-direction`, `wireframe`, `make-a-deck`, `make-a-prototype`, `make-tweakable`, `generate-variations`, `design-system-extract`, `component-extract`, `accessibility-audit`, `ai-slop-check`, `hierarchy-rhythm-review`, `interaction-states-pass`, `polish-pass`) are synced to `~/.claude/skills/`. Each is a phased procedure. When the task matches a skill's trigger (as described in the system prompt's "Available skills" chapter), read the relevant `~/.claude/skills/<name>.md` and follow it.
+
+## Step 3: Apply it to the request
+
+Apply the adopted design guidance to the following request:
+
+$ARGUMENTS
+
+Follow the workflow the system prompt lays out — ask clarifying questions first when the request is new or ambiguous, acquire design context before mocking from scratch, build a skeleton early, and run `polish-pass` before delivery.

package/claude/skills/accessibility-audit.md

@@ -0,0 +1,51 @@
+# Accessibility Audit: WCAG and Inclusive Design Review
+
+Review the current design for accessibility issues across contrast, semantic structure, keyboard navigation, motion, and forms. Fix any issues found. **Good accessibility is good design — it benefits everyone.**
+
+## Phase 1: Identify the surface to audit
+
+Audit the HTML file the user just edited or asked about; otherwise the most recently modified design file; if unclear, ask. Read it end-to-end and note the framework in use, the expected level (WCAG AA by default), and any user-stated constraints.
+
+## Phase 2: Launch four review agents in parallel
+
+Use the ${AGENT_TOOL_NAME} tool to launch all four agents concurrently in a single message, each with the full file contents.
+
+Instruct every agent explicitly: report every issue found, including borderline and low-severity ones, with a confidence and severity estimate. Coverage is the agent's job; filtering happens at aggregation (Phase 3).
+
+### Agent 1: Contrast and Color
+
+1. **Text contrast.** Normal text (under 18px) needs 4.5:1; large text (18px+ bold or 24px+) needs 3:1; UI components (buttons, icons, focus rings) need 3:1. Compute the actual ratio for any color pair you can resolve; flag every failing pair with the ratio and the required minimum.
+2. **Color-only signaling.** Flag any state communicated by color alone — green/red without an icon, links with no underline, charts with no legend or labels.
+3. **Difficult combinations.** Red+green (most common colorblindness), blue+yellow at similar lightness, light gray on white, colored text on colored backgrounds with similar brightness.
+4. **Whites and blacks.** Flag pure `#FFFFFF` on `#000000`; subtly toned (`#FAFAFA` / `#1A1A1A`) is preferred. Style recommendation, not WCAG.
+
+### Agent 2: Semantic HTML and Structure
+
+1. **Heading hierarchy.** Exactly one `<h1>`, no skipped levels; headings describe content, not visual size.
+2. **Right element for the role.** `<button>` not `<div onclick>`; `<a href>` not a styled `<div>`; `<label for>` linked to inputs; `<nav>`/`<main>`/`<article>`/`<section>`/`<aside>` landmarks.
+3. **Alt text on every meaningful image.** Decorative images get `alt=""`; meaningful images describe what they convey (`alt="Wireless headphones, side view"` not `alt="product"`).
+4. **Form labels.** Every input has an associated `<label>` (or `aria-label`). Placeholder text alone is not a label.
+5. **ARIA only when semantic HTML can't.** Flag `role="button"` on a `<div>` that could be a `<button>`.
+
+### Agent 3: Keyboard Navigation and Focus
+
+1. **Keyboard reachable.** Everything clickable is Tab-reachable — hover-only menus, mouse-only dropdowns, and keyboard-inaccessible modals fail.
+2. **Logical tab order.** Follows reading order; flag `tabindex` values greater than 0.
+3. **Interaction patterns.** Modals close on Escape; dropdowns open with Enter/Space and arrow-navigate; forms submit on Enter from a field.
+4. **Visible focus rings.** Flag `outline: none` without a visible replacement meeting 3:1 contrast against the adjacent background. Prefer `:focus-visible` over `:focus`.
+5. **Skip links.** Recommend "Skip to main content" on pages with significant repeated navigation.
+
+### Agent 4: Motion, Forms, and Misc
+
+1. **`prefers-reduced-motion` respected.** Animations beyond a couple hundred milliseconds need a `@media (prefers-reduced-motion: reduce)` block that shortens or removes them.
+2. **No flashing** more than 3 times per second (photosensitive epilepsy risk); flag and require pause controls.
+3. **Form errors** are specific ("Email address is invalid" not "Invalid"), tied to their field visually and via `aria-describedby`.
+4. **Required fields** marked with text and/or icon plus the `required` attribute, not color alone.
+5. **Input types and autocomplete.** `type="email"`, `type="tel"`, `autocomplete` attributes for autofill and mobile keyboards.
+6. **Hit targets** at least 44×44px on touch surfaces.
+
+## Phase 3: Aggregate and fix
+
+Wait for all four agents to complete. Aggregate their findings into a single deduplicated list and fix each issue directly. For borderline cases (e.g., contrast at 4.4:1), apply the fix anyway — accessibility is the floor, not the ceiling. If a finding is a clear false positive or out-of-scope (e.g., the agent flagged a third-party embed you can't modify), note it and skip it.
+
+Summarize: issues found by category (contrast / semantic / keyboard / motion-forms), issues fixed, and anything left for the user.

package/claude/skills/ai-slop-check.md

@@ -0,0 +1,71 @@
+# AI Slop Check: Detect and Fix Generic AI Aesthetics
+
+Review the current design for the visual tropes that signal "AI-generated template," and fix any found. These patterns read as default, not intentional — a design that looks like a hundred other AI outputs fails to look like the user's design.
+
+Each rule is **positive-first**: the default to reach for, then the patterns to detect and replace. At write-time, bias toward the default; at review-time, scan for the detection patterns.
+
+## Phase 1: Identify the surface
+
+Review the HTML/CSS file the user just edited or asked about; otherwise files modified this session; if unclear, ask. Read the file and skim referenced CSS, tokens, and component files so you can resolve actual values.
+
+## Phase 2: Single-pass review
+
+Apply each rule below in a single pass — these patterns are obvious enough that parallel dispatch is overkill. Report every detection, including uncertain or low-severity ones, with a confidence and severity estimate. Coverage is the job at this stage; filtering happens in Phase 3 or in `polish-pass` aggregation.
+
+### 1. Gradients — flat or subtle, on-tone
+
+**Default:** flat color from the design system, or a subtle on-tone two-stop gradient. Flat is almost always stronger.
+
+**Detect & replace:** rainbow / 3+ color gradients; saturated purple-to-pink, orange-to-pink, or other "trendy" blends on heroes, buttons, or large surfaces; gradient overlays on imagery that don't improve legibility or hierarchy.
+
+### 2. Emoji — functional or brand-driven only
+
+**Default:** no emoji, unless the brand uses them in existing materials, the emoji is functional (status indicator, category marker), or the user asked.
+
+**Detect & remove:** emoji prepending headlines, buttons, or list items (`🚀 Get Started`); repeated emoji filler (`🎉🎉🎉`); emoji bullets without meaning. If the layout relied on the emoji's visual weight, use a real icon (Feather, Material, Phosphor, Heroicons) or better typographic hierarchy.
+
+### 3. Cards — shadow, thin border, or background separation
+
+**Default:** subtle shadow, thin all-around border, or background separation. Reserve `border-left: 4px solid` for semantic emphasis (callouts, alerts, status).
+
+**Detect & replace:** `border-radius: 12px` + `border-left: 4px solid` used as the _default_ card style — this combination reads as "default SaaS template." Keep the left border only when it carries that semantic meaning, or when it comes from an existing design system you're matching.
+
+### 4. Imagery — real, licensed, or honest placeholder
+
+**Default, in order:** real photography (Unsplash, brand assets); professional illustration; honest placeholder — striped background with monospace label like `product shot (1200×800)`. A placeholder beats a bad illustration: it signals "asset needed" without pretending to be final.
+
+**Detect & replace:** custom SVG illustrations of people, scenes, or concepts not drawn by a skilled illustrator; "AI-style" character art (giant heads, flat-color blobs, identical posing); placeholder-quality decoration presented as final.
+
+### 5. Type — fonts chosen with intent
+
+**Default:** a font matched to the brand's tone or the medium. With no brand, suggest 2–3 alternatives matching the design's tone (geometric, humanist, modern, classical) and let the user pick.
+
+**Detect & question** bare use of Inter, Roboto, Arial, Fraunces, or bare system stacks as silent defaults. Keep them only if the brand specifies them or the user confirmed. Don't silently swap one generic for another.
+
+### 6. Color — subtly toned whites and blacks
+
+**Default:** whites and blacks toned to the palette — warm `#FFFAF0`/`#2D2118`, cool `#F5F7FA`/`#1F2937`, neutral `#FAFAFA`/`#1A1A1A`.
+
+**Detect & replace:** exact `#FFFFFF` background with exact `#000000` text — harsh, cold, and unfinished.
+
+### 7. Color values — trace to a token or harmonious palette
+
+**Default:** every color traces to a design token, brand variable, or `oklch()`-derived palette (use `oklch()` to keep lightness and chroma consistent when building from scratch).
+
+**Detect & consolidate:** colors that don't trace anywhere — five slightly different blues across one file means colors were invented inline.
+
+### 8. Spacing — snap to a 4px or 8px scale
+
+**Default:** spacing tokens (`--space-xs: 4px` through `--space-2xl: 64px`); multiples of 4 or 8 feel intentional.
+
+**Detect & replace:** off-scale values (`padding: 7px 15px`, `margin: 18px`, `gap: 13px`) — they feel chaotic.
+
+### 9. The editorial-warm house style — deliberate or absent
+
+**Default:** an aesthetic direction chosen for the brief (see `frontend-aesthetic-direction`). The warm-editorial look is legitimate for editorial, hospitality, and portfolio work — when it traces to a brand or an explicitly committed direction.
+
+**Detect & question** the combination, absent a brand reason: cream / warm off-white backgrounds in the `#F4F1EA` family; serif display faces as silent defaults (Georgia, Playfair Display, Fraunces); italic word-accents in headlines; terracotta / amber accents. Any one can be deliberate. All together — especially on a dashboard, dev tool, fintech, healthcare, or enterprise surface — is the default-template look, today's equivalent of the purple gradient. Replace with the committed direction, or flag for the user if none exists.
+
+## Phase 3: Fix and summarize
+
+Apply fixes directly. Where multiple options are reasonable (e.g., which non-Inter font), pick the most defensible default and note it so the user can override. Summarize: tropes found by category, fixes applied, open questions for the user.

package/claude/skills/component-extract.md

@@ -0,0 +1,52 @@
+# Component Extract: Identify Reusable Components from a Design
+
+Walk a design and identify the reusable components hidden inside it; emit a component inventory the user can turn into a component library or design system. Use this when the user has a finished page or flow and wants to "make it a system," "build a component library," or hand off structured pieces.
+
+**Pages are arrangements of components.** Extracting them turns a pile of one-offs into something maintainable.
+
+## Phase 1: Identify the surface
+
+Determine what to walk — a single design file, a multi-page flow, or a whole project. Read all relevant files and build a mental model of the visual vocabulary in use.
+
+## Phase 2: Walk the design and inventory
+
+Section by section, for each visual element ask:
+
+1. **Does this exact pattern appear more than once?**
+2. **Could it reasonably appear elsewhere?** (A card style, form input, or header likely repeats even if it's in one place now.)
+3. **Does it have variants?** (Button: primary/secondary/ghost. Card: with/without image.)
+4. **Does it have states?** (Hover, active, disabled, focus, loading.)
+
+Yes to any → component candidate. Group findings into the standard categories:
+
+- **Foundational** — color, spacing, type, radius, shadow, and motion tokens (see `design-system-extract` for token-level detail)
+- **Atoms** — button, input, checkbox/radio/toggle, select, tag/chip/badge, avatar, icon (sizes + set in use), link
+- **Molecules** — form field (label + input + helper + error), card, toast/alert, modal, dropdown menu, tooltip, pagination
+- **Organisms** — header/nav, footer, sidebar, tab group, table, form, hero, feature grid, empty state
+- **Templates** — landing, detail, list/index, empty-state page
+
+## Phase 3: For each component, document
+
+- **Name** — short, conventional (e.g., `Button`, `FormField`)
+- **Purpose** — one sentence on when to use it
+- **Variants** and **sizes**
+- **States** — default, hover, active, focus, disabled, loading (whichever apply)
+- **Tokens used** — which color, spacing, type tokens it references
+- **Composition** — what other components it's built from (e.g., `Card` uses `Button`)
+- **Accessibility notes** — keyboard support, ARIA, contrast
+- **Do / Don't** — at least one of each (e.g., "Don't stack two primary buttons in a row")
+
+## Phase 4: Identify the gaps
+
+Flag these as part of the deliverable — they're the work needed to turn the design into a real system:
+
+- **Inconsistencies** — three slightly-different button styles where one should serve; recommend a canonical version
+- **Missing states** — hover without focus, no disabled state
+- **Missing variants** — e.g., delete actions in the design but no destructive button
+- **Off-scale values** — spacing or sizes outside the established token scale; snap them
+
+## Phase 5: Emit and hand off
+
+Write the inventory to a file (e.g., `component-inventory.md`), one section per component, structured as above — a doc the user can hand to a developer. Optionally render a "component library" page showing each component with its variants and states (the `design_canvas.jsx` starter works for the grid).
+
+Then suggest next steps: `design-system-extract` for tokens if not already done, building the library as real code, `polish-pass` on the components, or `make-tweakable` on the library. Summarize: components inventoried by category, inconsistencies and gaps flagged, output file path, recommended next step.

package/claude/skills/design-system-extract.md

@@ -0,0 +1,75 @@
+# Design System Extract: Pull Tokens from Sources
+
+Extract design tokens (color, typography, spacing, radii, shadow) from a brand reference, codebase, or screenshots, and emit a structured tokens file. Use this when starting design work that should match an existing visual language. Once tokens exist, future designs reference them — keeping the system consistent without re-asking the user for values.
+
+## Phase 1: Identify sources
+
+The user may provide a codebase (read theme files: `theme.ts`, `tokens.css`, `_variables.scss`, `tailwind.config.js`, design system source), a live site or screenshots, a brand guide (PDF, Figma, doc), or an existing UI kit project. If unspecified, ask — invented tokens defeat the point.
+
+## Phase 2: Extract by category
+
+Capture concrete values from the source — never guess.
+
+### Colors
+
+- **Brand primary and accent** (with dark/light variants where defined)
+- **Semantic** — success, warning, error, info (plus their light backgrounds where defined)
+- **Neutral scale** — typically 9–11 steps from near-white to near-black, consistent tone (warm / cool / neutral)
+- **Surfaces** — background, foreground, card, overlay, border
+
+For each: the hex (or oklch) value, its name in the source, and its documented usage. Flag inconsistencies — multiple slightly different blues, neutrals on different tones — as findings for the user. Don't silently merge them; the inconsistency itself is information.
+
+### Typography
+
+- **Families** — sans, serif, mono, with full fallback stacks
+- **Sizes** — the actual scale in use, not a generic one
+- **Weights** — only those actually loaded
+- **Line heights** — at minimum tight (~1.1) for headlines, normal (~1.5) for body, loose (~1.7) for long-form
+- **Letter spacing** — usually only matters for all-caps labels
+- **Named text styles** ("Heading 1", "Body Large", "Caption") if the source defines them
+
+### Spacing
+
+The actual scale in use (common bases: 4px or 8px, typically running to 64–128px). If the source has separate scales for inset / inline / block / between-components, capture all of them.
+
+### Radii and shadows
+
+Corner-radius values (typically 3–5 distinct: `0 / 4 / 8 / 12 / 9999`) and the elevation scale with full CSS values (offset, blur, spread, color, opacity).
+
+### Other tokens, if present
+
+Z-index scale, animation durations and easings, breakpoints, container widths.
+
+## Phase 3: Emit the tokens file
+
+Write a `tokens.css` — or match the source's format and naming convention (`tokens.ts` with typed exports, `tokens.json`, a Tailwind config extension). Group by category with clear names:
+
+```css
+:root {
+	/* Brand */
+	--color-primary: #...;
+	--color-accent: #...;
+	/* Semantic */
+	--color-success: #...;
+	--color-error: #...;
+	/* Neutrals */
+	--color-gray-50: #...; /* … through --color-gray-900 */
+	/* Surfaces */
+	--color-bg: #...;
+	--color-surface: #...;
+	--color-border: #...;
+
+	--font-sans: "...", -apple-system, sans-serif;
+	--text-base: 16px; /* full size scale as found */
+	--weight-regular: 400; /* only loaded weights */
+	--leading-normal: 1.5;
+
+	--space-1: 4px; /* full spacing scale as found */
+	--radius-md: 8px;
+	--shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
+}
+```
+
+## Phase 4: Document findings
+
+Summarize: **sources used**; **categories extracted**; **gaps** — token sets the source doesn't define (these are the user's decisions to make; don't fill them silently); **inconsistencies** — near-duplicate values or off-scale outliers worth consolidating; **recommended next steps** — typically review the file with the user, then use it in subsequent designs.

package/claude/skills/discovery-questions.md

@@ -0,0 +1,60 @@
+# Discovery Questions: Kickoff Question Protocol
+
+Run a structured question round at the start of new or ambiguous design work. **Asking good questions is the single biggest lever for design quality** — bad designs come from missing context, not missing skill.
+
+## Phase 1: Read what's already attached
+
+Before asking anything, read every attached resource — codebases, screenshots, brand guides, linked design systems or UI kits, the stated brief. Asking "do you have a brand guide?" when they just attached one is the fastest way to lose the user's confidence.
+
+## Phase 2: Decide whether to ask
+
+**Ask when** the work is new or ambiguous; the output, audience, or fidelity is unclear; you don't know which design system, UI kit, or brand is in play; the variation count is unspecified; or the task leaves multiple non-trivial dimensions open.
+
+**Skip when** the user gave you everything; it's a small tweak or follow-up; scope, audience, and constraints are explicit; or the task is "recreate this exact thing."
+
+If the open question changes the design's direction (audience, format, brand, scope), ask. If it's a minor choice you can defensibly make yourself (a label, a default value, two equivalent approaches), decide, build, and note the decision in your summary instead of asking.
+
+## Phase 3: Build the question set
+
+Include the following **always-ask** questions, plus the problem-specific questions the brief actually leaves open (typically 3–6):
+
+- **Starting point** (non-negotiable — starting hi-fi work without context produces bad design). "Is there a UI kit, design system, codebase, brand guide, or screenshots I should match? If not, I'll need to commit to an aesthetic from scratch — confirm that's OK."
+- **Variations.** How many of the overall design? On what axes (visual, layout, interaction, copy, tone)? Variations of specific elements ("how many heroes?")?
+- **Novelty.** By-the-book, novel/creative, or a mix?
+- **Tweaks.** What should be adjustable live in the final design (colors, copy, layout, components)?
+- **Focus axis.** Flows, copy, or visuals — where should exploration effort go?
+
+Problem-specific examples:
+
+- **Deck:** audience and knowledge level; time budget / slide count; tone; speaker notes; existing source material?
+- **Landing page:** desired user action; primary persona; references admired or rejected; mobile-first or desktop-first?
+- **Prototype:** flow and screens; hi-fi or mid-fi; device frame; goal state; sample data?
+- **Brand / aesthetic:** three adjectives; admired designs (and what specifically); off-limits; industry context?
+
+Size the round to the ambiguity: a genuinely open brief may warrant ~10 questions; a half-specified one may need only 3–4. Never pad the round to hit a number — a question whose answer wouldn't change what you build is noise.
+
+## Phase 4: Format the question round
+
+Use the `questions_v2` tool — it renders native form components the user answers in a structured way. Per question:
+
+- **Prefer multiple choice**; always include "Explore a few options" and "Decide for me" as escape hatches, plus "Other" for open-ended fallback
+- **SVG options** for visual choices (layout, icon style, color swatch, mood); **sliders** for numeric ranges (generous bounds); **file-pickers** for assets; **freeform** for genuinely open questions
+
+Order most-important-first — the form streams in, and the user can start answering before the rest loads. Keep titles short; subtitles are optional clarifications.
+
+## Phase 5: End the turn, then confirm
+
+`questions_v2` does not return an answer immediately — after calling it, **end your turn**. Don't anticipate answers and proceed. When answers come back, read all of them, then:
+
+- Briefly recap the choices that most affect the design
+- Note answers you'd push back on (gently — the user is the manager)
+- Proceed to the appropriate building skill (`make-a-deck`, `make-a-prototype`, `wireframe`, etc.) and execute autonomously. This round was your chance to ask — don't come back with follow-up questions for minor decisions; make them and list them in your summary.
+
+If you later discover an early answer was wrong (e.g., the user said "no novel ideas" but their feedback wants bolder choices), surface the contradiction and re-question rather than carrying the wrong assumption.
+
+## Anti-patterns
+
+- **Don't skip asking.** "I'll just start building" produces designs that miss the brief.
+- **Don't ask everything.** Cap around 10–15; bundle into one form, not one-at-a-time across turns.
+- **Don't ask what you can derive.** If the attached brand guide has the primary color, don't ask for it.
+- **Don't ask to be safe.** A question is justified by the design impact of its answer, not by your uncertainty.

package/claude/skills/frontend-aesthetic-direction.md

@@ -0,0 +1,76 @@
+# Frontend Aesthetic Direction: Commit to a Look When No Brand Exists
+
+Establish an aesthetic direction (typography, color, density, mood, component style) when the user is designing without an existing brand or design system. Use this **before** hi-fi work in a greenfield context: mocking hi-fi from scratch without committing to an aesthetic is the fastest path to AI-template output. Pick a direction first, then design within it.
+
+## Phase 1: Confirm there's truly no existing context
+
+Double-check: no brand guide, no existing app or product to match, no reference site the user wants to mimic, no partial design system in the codebase. If any exist, **stop and use them** — aesthetic direction is for true greenfield. If the user has a brand and forgot to attach it, ask for it before proceeding.
+
+## Phase 2: Discover the intent
+
+Ask the user (or confirm if stated): **three adjectives** for the desired feel; **audience**; **industry context**; **reference designs they admire** (and what specifically — the type, spacing, color, tone, density?); **off-limits** aesthetics or tropes.
+
+If the user is unsure, propose **4 distinct visual directions**, each specified concretely — background hex / accent hex / display + body typeface, with a one-line rationale tied to the brief — and let them pick. The directions must not share a palette family: four takes on warm-cream is one direction, not four. Make at least one deliberately off-distribution.
+
+## Phase 3: Commit to the system — make it concrete
+
+Vague aesthetic statements ("modern and clean") produce generic designs. Commit on each axis:
+
+### Typography
+
+Pick **specific** fonts — headline, body (often the same family), and mono if needed — with weights and a type scale. 1–2 families maximum.
+
+Avoid the overused defaults — Inter, Roboto, Arial, bare system stacks, and the silent serif-display defaults (Fraunces, Playfair Display, Georgia-as-display). Pick with intent: a humanist sans (Söhne, Suisse), a modern serif (Tiempos, GT Sectra), an editorial classic (Tiempos Headline, Canela), a typewriter mono (JetBrains Mono, IBM Plex Mono), a geometric sans (Söhne Buch, Visby), depending on the mood. If a paid foundry may be out of reach, name the closest free alternative (e.g., Söhne for production, Albert Sans / Geist free).
+
+### Color
+
+Pick a tone — warm (cream, gold, terracotta), cool (gray, slate, ice, blue), or neutral (concrete, charcoal, off-white).
+
+**The warm-editorial combination (cream background + serif display + terracotta/amber accent) is the current default-model look.** Choose it only when the brief is genuinely editorial, hospitality, or portfolio — and say so explicitly in the direction block. If the direction drifts there without a stated reason, pick again.
+
+Then pick: a primary brand color (with light/dark variants), at most one accent, semantic colors (success/warning/error/info), and a 5–10 step neutral scale on the chosen tone. Use `oklch()` for harmony when building from scratch (`--brand-primary: oklch(55% 0.18 250)`). Subtly tone whites and blacks — pure `#FFFFFF`/`#000000` is harsh; match the tone (e.g., `#FAFAFA` / `#1A1A1A`).
+
+### Density
+
+Pick a spacing scale (4px or 8px base) and a density — tight (compact dashboards, dense data UIs), normal (typical product UI), or loose (editorial, marketing, premium, generous whitespace). Density is felt as much as seen.
+
+### Border radius and shadow
+
+Sharp (0–2px — utilitarian, brutalist, editorial), soft (4–8px — typical modern product), or pill/fully-rounded (playful, friendly, consumer). Shadows likewise: sharp / soft / none. One elevation system, not a mix.
+
+### Component style
+
+Filled, ghost, outlined, or elevated. Pick a default, with secondary styles for hierarchy.
+
+### Imagery and iconography
+
+Real photography (Unsplash, brand, stock), professional illustration, icons from an established set (Feather, Material, Phosphor, Heroicons), or honest placeholders when assets aren't available. Avoid hand-drawn SVG illustrations.
+
+### Motion
+
+Quiet (transitions on state changes only, 200ms ease), expressive (entrance animations, scroll-driven reveals), or playful (springs, micro-interactions on hover). Commit to one mode — mixed motion feels unintentional.
+
+## Phase 4: Document the direction
+
+Write the direction into the file — a comment block at the top of the source AND a visible "design system summary" in the rendered output, like a junior designer showing their thinking:
+
+```
+/* Aesthetic direction:
+ * Editorial / serious / spacious.
+ * - Type: Tiempos Headline (display) + Söhne (body). Free alt: GT Sectra → Albert Sans.
+ * - Color: cool-neutral. #FAFAFA bg / #1A1A1A text. Brand: oklch(55% 0.18 250) deep blue. No accent.
+ * - Density: loose. 8px scale, generous padding.
+ * - Radius: 4px. No shadow — borders only.
+ * - Components: ghost buttons; filled for primary CTA only.
+ * - Imagery: real photography, full-bleed.
+ * - Motion: quiet. 200ms ease, no entrance animations.
+ */
+```
+
+## Phase 5: Apply, test, and keep consistent
+
+Build a small surface (a hero, a card, a button group) with the direction and show it to the user early. Ask: "Does this read as [the three adjectives]?" If not — or the user pushes back on an axis — revise before going broader. A direction that fails at small scale gets worse as it scales up, not better.
+
+Every subsequent design references the direction's tokens, not new inline values. If a new design needs an undefined value, **add it to the direction first**, then use it. When the direction matures, extract it into a tokens file (`design-system-extract`).
+
+Summarize: the three adjectives, the committed choices per axis, any axes the user should review before you go broader, and the first surface built with the direction.

package/claude/skills/generate-variations.md

@@ -0,0 +1,40 @@
+# Generate Variations: Produce 3+ Design Options
+
+Produce multiple distinct design variations of a screen, component, or flow so the user can mix and match the strongest pieces. Use this when the user asks for options, alternatives, "different takes," or "show me a few." **Variations are the cheapest path to good design** — one design is one bet; three let the user reject what they don't want and combine what they do.
+
+## Phase 1: Establish the baseline
+
+Confirm: **what is being varied** (screen, component, flow, visual treatment — scope determines how many variations are useful); **existing design context** (variations should root in the UI kit / design system unless explicitly asked to break free); **number** (default 3; 5–6 is a healthy ceiling); **axis preference** (visuals, interactions, layout, or copy/tone — where does the user want exploration weighted?).
+
+## Phase 2: Pick the axes
+
+Pick 2–4 dimensions to vary across: visual treatment (color tone, density, shadow, radius, type weight); layout (centered vs asymmetric, single vs multi-column, full-bleed vs inset); interaction model (single page vs multi-step, modal vs inline); information hierarchy; tone; component style. Write down which axis each variation flexes — it makes the comparison legible to the user.
+
+## Phase 3: Build with intent — basic to bold
+
+Order from most by-the-book to most novel:
+
+1. **By the book.** Matches existing patterns and conventions — the safe option.
+2. **Refined.** Same structure, one or two dimensions pushed — bolder type, more confident layout, more expressive color. Often the user's actual pick.
+3. **Novel.** A genuinely different take — unconventional layout, strong visual metaphor, daring aesthetic. Stretches the conversation and surfaces preferences the user didn't know they had.
+4. **4–6 (if requested).** Hybrids along the spectrum, or a wildcard on a different axis.
+
+**Cover both ends.** All-safe wastes the user's time; all-wild ignores the brief.
+
+## Phase 4: Vary substantively, not cosmetically
+
+Variations should differ in layout, hierarchy, what's primary, type system, density, interaction approach, or copy strategy — not just button color, accent shade, or shadow opacity. If two are too close, drop one for a more substantive alternative. The user should be able to articulate the difference between any two variations in one sentence.
+
+**Specify each variation concretely before building it** — distinct palette family, distinct type pairing, distinct layout skeleton, written down per variation. Variety must be designed, not hoped for: left unspecified, variations drift toward one default look (typically the warm-editorial house style). For the novel variation, deliberately pick something off-distribution and interesting.
+
+## Phase 5: Present in a single file
+
+Use the `design_canvas.jsx` starter for static variations side-by-side, or **tweaks** (`make-tweakable`) if the variations share structure and differ on a few axes. For flows, build each variation as a small storyboard within the canvas. **Do not produce v1.html / v2.html / v3.html** — one file, all variations visible or toggle-able.
+
+## Phase 6: Annotate and recommend
+
+Caption each variation in one or two sentences ("Variation 2 — Refined. Same structure, expressive headline type, warmer palette."). The captions are a thinking tool: if you can't write a clear one, the variation isn't distinct enough.
+
+End with a clear recommendation — the user decides, but a designer offers an opinion ("Variation 2 is my pick — the safety of 1 with more visual confidence"). Don't hedge that all options are equally good; they aren't.
+
+Then suggest the next step: a refinement round on the chosen direction, another variation round on a different axis, `make-a-prototype` to go interactive, or `polish-pass` if the user is ready to ship.

package/claude/skills/hierarchy-rhythm-review.md

@@ -0,0 +1,50 @@
+# Hierarchy and Rhythm Review
+
+Review the current design for visual hierarchy and rhythm — the two qualities that most distinguish "intentional" from "AI-generated" — and fix issues found. **Hierarchy guides the eye** (what gets looked at first, second, third); **rhythm makes the design feel intentional** (repetition with strategic variation). When they're right, the design feels effortless to scan.
+
+## Phase 1: Identify the surface
+
+Review the HTML/CSS file the user just edited or asked about; otherwise the most recently modified design file; if unclear, ask. Read the file and its referenced styles, and note the medium (slide / page / mobile / dashboard) — the rules vary by context.
+
+## Phase 2: Launch two review agents in parallel
+
+Use the ${AGENT_TOOL_NAME} tool to launch both agents concurrently in a single message.
+
+Instruct both agents explicitly: report every issue found, including uncertain and low-severity ones, with a confidence and severity estimate. Coverage is the agent's job; filtering happens at aggregation (Phase 3).
+
+### Agent 1: Hierarchy review
+
+For every screen, slide, or major section:
+
+1. **Primary / secondary / tertiary.** What should be looked at first, second, third? If you can't tell, the hierarchy is broken.
+2. **Size.** Headings visibly larger than body; primary CTA larger than secondary actions. Flag similar content at very different sizes (inconsistent) and different-importance content at similar sizes (flat).
+3. **Color.** Primary actions in saturated brand color, secondary in neutral, de-emphasized in light gray. Flag everything-same-color (no signal) and unimportant-elements-brightest (wrong signal).
+4. **Weight.** Headlines bold, body regular, captions light. Flag everything-bold and everything-regular.
+5. **Position.** Eyes start top-left (in LTR); the most important content belongs in prime real estate. Flag primary elements buried bottom-right.
+6. **Density.** Loose spacing signals "pay attention," tight signals "supporting." Flag important content crammed while filler breathes — that's reversed.
+7. **The 5-second test.** A first-time user should know what to look at and what to do within 5 seconds.
+
+### Agent 2: Rhythm review
+
+For the document as a whole:
+
+1. **Spacing scale.** All padding/margin/gap values snap to a consistent scale (multiples of 4px or 8px). List the implicitly-used scale and flag outliers (`padding: 7px`, `gap: 13px`).
+2. **Type scale.** Flag arbitrary sizes (`17px`, `23px` in a 16/20/24 design).
+3. **Repetition.** Cards in a grid, list items, feature blocks share padding, gap, sizes, structure. Flag near-duplicates that are subtly different — identical or deliberately different, nothing in between.
+4. **Strategic variation.** A long page or deck breaks its pattern occasionally (background shift, wider section, centered CTA). Flag total uniformity (monotonous) and every-section-different (chaotic).
+5. **Palette discipline.** 3–5 colors plus tints/shades. Flag 8+ distinct colors, or slightly different blues/grays in different places.
+6. **Section structure.** Sections visually distinguishable (background change, divider, padding shift) but consistently so. Flag no separation and too many separation styles.
+7. **Alignment.** Flag elements off-grid by a few pixels — inconsistent margins rather than intentional offset.
+
+## Phase 3: Aggregate and fix
+
+Wait for both agents, aggregate findings, then fix directly:
+
+- Random spacing / font sizes → snap to the file's scale (define one — 4px or 8px multiples — if missing)
+- Flat hierarchy → introduce contrast (bigger headlines, more prominent primary CTA, consistently neutral body)
+- Reversed hierarchy → swap the signals (mute the loud unimportant element, reposition the buried primary)
+- Monotony → introduce one strategic break; chaos → consolidate to the strongest pattern
+
+For ambiguous cases, lean toward the more aggressive hierarchy — too-strong is easier to dial back than too-weak to dial up.
+
+Summarize: issues found and fixed per category, judgment calls the user should review, open recommendations.

package/claude/skills/interaction-states-pass.md

@@ -0,0 +1,38 @@
+# Interaction States Pass
+
+Verify every interactive element has a complete set of states (default, hover, active, disabled, focus, loading) plus transitions and feedback; add what's missing. **Interactive elements without state feedback feel broken** — a button without hover looks like a label; a removed focus ring locks out keyboard users. This is the safety net before a design is shown to users.
+
+## Phase 1: Inventory interactive elements
+
+Walk the design and list every interactive element: buttons (including `role="button"` and anything with a click handler), links, form inputs, toggles (checkboxes, radios, switches), clickable cards or rows, navigation items (tabs, sidebar links, breadcrumbs), and custom widgets (dropdowns, accordions, modals, popovers).
+
+## Phase 2: Per-element state verification
+
+Check all six aspects for each element. Flag everything, including borderline cases — note a confidence level rather than silently dropping a finding you're unsure about.
+
+1. **Default.** Clearly interactive at rest: buttons have fill or border distinct from body text; links look like links; inputs have visible borders or fills. Flag elements that only reveal interactivity on hover — touch and keyboard users never hover.
+2. **Hover.** Visual change on cursor-over — at minimum a color shift; better, color + shadow + slight transform (`translateY(-2px)`). Don't use opacity reduction as hover; it reads as disabled.
+3. **Active / pressed.** Darker color, slight scale-down (`transform: scale(0.98)`), or return-to-baseline — confirms the click registered before the action completes.
+4. **Disabled.** Lower opacity (~0.6), no hover effect, `cursor: not-allowed`, distinct from both default and hover. If disabled pending a condition ("fill all required fields"), indicate _why_ — tooltip, inline message, or `title` attribute.
+5. **Focus.** Visible ring via `:focus-visible` (not bare `:focus`): 3:1 contrast against the adjacent background, at least 2px thick with 2px offset. `outline: none` is **never** used without a replacement.
+6. **Loading** (for elements that trigger async work). Disable on click to prevent double-submission, swap the label for a spinner or "Loading…", restore on completion. Data fetched on render gets a skeleton, spinner, or progress indicator.
+
+## Phase 3: Verify transitions
+
+Every state change transitions smoothly, not snapped (`transition: background 0.2s ease, transform 0.2s ease, box-shadow 0.2s ease`):
+
+- **0.15–0.3s** for state changes (hover, focus, active); **0.3–0.5s** for entry/exit (modals, drawers, toasts)
+- Avoid over 0.5s on micro-interactions (laggy) and 0s / no transition (broken)
+- Wrap motion-heavy transitions in `@media (prefers-reduced-motion: reduce)`
+
+## Phase 4: Verify feedback for actions
+
+Every action shows a visible result: submission success (toast, inline message, or redirect with confirmation), submission failure (clear error, tied to the field if field-specific), validation errors (appear on blur or submit, cleared when fixed), state changes (immediate visual update). Flag silent successes and silent failures — both feel broken.
+
+Current state is visible too: the active page or tab, selected items, and active filters or sorts are visually distinct.
+
+## Phase 5: Apply fixes and summarize
+
+Add each missing state or feedback element using the design system's tokens. Where the system doesn't define one, use: hover 10–15% darker (or `color-mix`); active another 10% or `scale(0.98)`; disabled opacity 0.6 + `cursor: not-allowed`; focus `outline: 2px solid var(--color-primary); outline-offset: 2px`; transition `0.2s ease`. Where the right state isn't obvious (e.g., a toggle button's hover-on-active), make a judgment call and note it.
+
+Summarize: elements inventoried, states added by category, transitions added or normalized, feedback added, judgment calls the user should review.