--- name: design description: > Unified design orchestrator for every app (golf/Bagman, portfolio, hive, keepings). Use when building UI components, designing screens, creating mocks, reviewing design compliance, updating design tokens, exploring color palettes or typography, implementing animations/motion, or doing any visual/frontend work. Also use when the user mentions "design system", "make it look better", "fix the UI", "design review", "polish this", "update the theme", or references any app's visual style. Also use when the user says design studio, golf design studio, studio sketch, flow sketch, primitive library, or app-specific design studio. Triggers proactively on ANY frontend/mobile file changes to ensure design compliance. This skill replaces golf-ui and is the primary studio router for every app, including golf. disable-model-invocation: false --- # Design Orchestrator You own the design METHOD for every app — golf (Bagman), portfolio, hive, keepings, and any app added later. Each app's own brand, primitives and law live in that app's repo at `.claude/skills/design/SKILL.md`, which loads automatically when you work there; this skill supplies the workflow that is identical across all of them. Adding an app requires no change to this skill. ## How This Skill Works This skill is a thin orchestrator. It: 1. Detects which app and platform (web/mobile) from the files being touched 2. Reads the repo's own design pack — `/.claude/skills/design/SKILL.md` (auto-loaded) + `/DESIGN.md` 3. Invokes **external design skills** under the hood for specialized work (see below) 4. Applies motion, anti-pattern, and quality principles consistently The heavy lifting comes from installed skills — this skill coordinates them and adds your project-specific standards. ### `DESIGN.md` is the token source of record When a repo has a root `DESIGN.md`, read it FIRST and prefer its values over any token table in this skill or in an app pack. It follows the [DESIGN.md spec](https://github.com/google-labs-code/design.md): YAML frontmatter carrying `colors`, `typography`, `rounded`, `spacing` (and optionally `components`), then up to eight markdown sections in a fixed order. It outranks every other token surface for one reason: in golf it is **generated** from `packages/tokens/src/theme-source.ts` and diffed by `tokens:check` in CI, so it cannot disagree with the tokens the app actually ships. A repo's `.claude/skills/design/SKILL.md` is hand-maintained and can lag — treat it as context and fallback, not as truth, wherever DESIGN.md covers the same ground. **Never hand-edit a generated `DESIGN.md`.** Its Overview says so and the CI diff rejects it. Change `theme-source.ts`, then run `pnpm --filter @bokendell/golf-tokens tokens:gen`. Two things it deliberately does not carry — do not read absence as permission: - **Components.** golf lists the section in `omitted` because the spec allows only 8 component sub-tokens (`backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`) and golf's components carry shadow, motion, glass and focus-ring state that none of those express. Component truth stays in golf-ui and the flow sketches. - **Dark values.** The frontmatter carries the LIGHT palette only — the spec has a single palette. Both modes are tabulated under `## Colors` in the body, so read that table before assuming a token is theme-independent. Its `## Do's and Don'ts` is derived from `packages/ui/HARD-RULES.md`, which remains the enforced source and carries the rationale and accepted alternative for each rule. Read HARD-RULES when a rule needs interpreting, not just obeying. ## Required external design skills (check before invoking) This orchestrator delegates the actual taste/craft/finishing/heuristics/HTML-prototyping work to upstream resources. Before any design work, verify they are installed. The canonical reference (sources, roles, exact install commands) is at: → `~/repos/bokendell/skills-marketplace/references/design-stack.md` (or in the cache at `~/.claude/plugins/cache/bokendell-skills/references/design-stack.md`) **Quick install summary:** | Skill | Install command | |---|---| | `/taste:design-taste-frontend` (v2; v1 fallback `/taste:design-taste-frontend-v1`) | `/plugin install taste@bokendell-skills` (Leonxlnx/taste-skill, sourced live). NOTE the invocable name is the SKILL.md `name:` (`design-taste-frontend`), NOT the folder `taste-skill`. The marketplace `skills` array must list each skill DIRECTORY — pointing at the bare `./skills` container registers zero skills. | | `/impeccable:impeccable` | `/plugin marketplace add pbakaus/impeccable` + `/plugin install impeccable@impeccable` | | `/emil-design-eng` + `/apple-design` (+ on-demand `/improve-animations`, `/review-animations`, `/animation-vocabulary`) | `npx skills add emilkowalski/skill` — installs all 5 as skills.sh universal skills (`.agents/skills/`, symlinked for Claude Code, tracked in `skills-lock.json`). `emil-design-eng` = Emil Kowalski's polish/component/motion philosophy; `apple-design` = Apple fluid-motion + materials + typography. The two are the always-load craft floor for app UI; the animation trio is motion-work-only. | | `/ui-ux-pro-max` | `/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill` + `/plugin install ui-ux-pro-max@ui-ux-pro-max-skill` | | `/huashu-design` | `git clone https://github.com/alchaincyf/huashu-design ~/.claude/skills/huashu-design` *(upstream isn't a plugin — installs as user-scope skill; `git pull` to update)* | **Verification:** quickly check each is present — ```bash ls ~/.claude/plugins/cache/bokendell-skills/taste/*/skills/ 2>/dev/null ls ~/.claude/plugins/cache/impeccable/impeccable/*/ 2>/dev/null ls ~/.claude/plugins/cache/ui-ux-pro-max-skill/*/*/ 2>/dev/null ls ~/.claude/skills/huashu-design/SKILL.md 2>/dev/null ls ~/.claude/skills/{emil-design-eng,apple-design}/SKILL.md 2>/dev/null # Emil (skills.sh) ``` If any is missing, **stop and surface the install command to the user** rather than degrading silently. ## Words are not your job — hand them to `copy` This skill owns pixels, motion, and layout. The moment you're deciding what a button SAYS, what an empty state's message reads, or whether copy sounds AI-written, invoke the **`copy`** skill instead (same plugin). It carries the voice dials, the humor-by-surface matrix, and the AI-slop tells; the app's own `docs/design/voice-and-copy.md` is the law it enforces. A mock with placeholder words is an unfinished mock: pull the real strings through `copy` before you call a board done. ## App Detection Detect the app from file paths or user mention: | Signal | App | |--------|-----| | `golf/apps/`, `golf/packages/`, "fairway", "golf" | **golf** | | `portfolio/apps/`, `portfolio/packages/`, "portfolio" | **portfolio** | | `hive/apps/`, `hive/packages/`, "hive", "agents" | **hive** | | `keepings/`, `apps/design/src/packages/{mobile,site}/`, "keepings", "capture" | **keepings** | | `packages/shared/ui/` | **shared** (compare across repos; read each repo's own DESIGN.md) | Detect platform: | Signal | Platform | |--------|----------| | `apps/*/mobile/`, `.tsx` in mobile paths, "mobile", "native", "expo" | **mobile** (React Native) | | `apps/*/app/`, `apps/*/admin/`, "web", "admin", "dashboard", "next" | **web** (Next.js) | **If the app is ambiguous** (shared packages, no path signal, new surface): ASK which app before composing — the apps share one workflow but different tokens, and guessing the wrong pack poisons everything downstream. Each app's pack lives in its own repo at `.claude/skills/design/SKILL.md` and is auto-loaded there; the pack also names where that app's **living design law** (flow `decisions.md` files) and **fidelity anchors** live. ## Studio Router — the app pack lives in the app's repo When the prompt mentions "design studio", "studio sketch", "flow", "primitive", "kit", or `swarm design`, stay in this skill for the METHOD and read the app pack from the repo you are working in: ``` /.claude/skills/design/SKILL.md ← brand character, primitives, studio workflow, repo law /DESIGN.md ← tokens, generated + CI-diffed (golf today) /packages/ui/HARD-RULES.md ← the enforced rules ``` Project skills load automatically, so in golf, hive, portfolio and keepings that pack is already in context — you do not need to go find it. If it is missing, say so rather than designing from memory. **Why the packs are not in this marketplace.** They used to be, and they drifted: every OKLch value in the old `references/apps/golf.md` was wrong against the shipped tokens (`bg` listed as `0.962 0.012 85` against `0.956 0.013 87`, the accent off by 0.06 chroma). A pack stored away from the code cannot be reviewed in the PR that changes the code. In-repo it can also be *generated* — which is what `DESIGN.md` now is. Three further reasons, from the Claude Code skills docs: cloud and Cowork sessions load a repo's committed `.claude/skills/` but never `~/.claude/skills/`; plugin skills are namespaced (`dev:design`) so a repo-level `/design` cannot collide; and a nested `.claude/skills/` inside a package loads only when that package is touched. **Adding a new app requires no change here.** Give the repo a `.claude/skills/design/SKILL.md` and, where it has a `theme-source.ts`, a generated `DESIGN.md`. Do NOT create a per-app top-level skill (`-design-studio`) in this marketplace — that scales linearly with apps and puts app truth back where it drifts. If the app cannot be inferred from path or product words, ask one short question before composing. ## Ground Truth Protocol (do this before composing ANY visual) Skills carry principles; the project's achieved taste lives in its **shipped screens** and its **accumulated decision law**. Both are mandatory inputs: 1. **Shipped-app screenshots.** Read the newest set from the app's screenshot folder (golf: `docs/design/app-screens/`, see the app pack; tracked in GOLF-462). If the folder is missing, stale (>2 weeks or the user says the UI changed), or doesn't cover the surface you're designing — ASK the user for 3–5 current screenshots before producing anything. Never compose from memory of older mocks; the live app outranks every prior design artifact. 2. **The decision law.** Read the relevant flow's `decisions.md` (append-only, newest-first) before composing. Locked rounds are LAW — design inside them, never re-litigate silently. 3. **Fidelity anchors.** Open your work by declaring which shipped artifacts you're matching ("anchoring on: Resume Slip, score chips, hole-hero card"). When a brief is vague, ask *"which existing screen should this feel like?"* — a named artifact beats any adjective. 4. **Self-verify before delivering.** After building any sketch/board, screenshot it yourself with Playwright at phone width (~400px) against the local studio or `file://`, LOOK at it, and fix what's broken (floating elements, missing assets, contrast) before the user sees it. For web surfaces, prefer driving the running dev server; if the workspace isn't up, ask the user to start it rather than skipping verification. 5. **Correction protocol.** When the user says output looks "basic / generic / AI-slop": do not iterate adjectives. Ask for (or propose) a concrete in-app artifact as the new anchor, then rebuild around that metaphor. ## Exploration engine: Claude Design `/design` (adopted 2026-08-21) Variant EXPLORATION runs on Claude Code's `/design` command (Claude Design artboards) whenever it is available; the hand-built HTML boards + tunnel protocol below become the FALLBACK (research-preview outage, offline, or a board that must be interactive in ways artboards can't express). The method does not change — the engine does. **The pipeline — each step keeps its owner:** 1. **Brief (ours).** Before invoking `/design`, assemble the same ground truth this skill always required — repo design pack, generated `DESIGN.md` (import it: it follows the design-system spec Claude Design consumes, and it is CI-diffed against the shipped tokens so artboards start on-brand), the flow's `decisions.md` locks, current app screenshots, and the craft skills (taste / emil-design-eng / apple-design / impeccable) DISTILLED INTO THE PROMPT — Claude Design cannot invoke skills, so the brief carries them. 2. **Explore (theirs).** `/design` 3-4 GENUINELY different directions, both themes, same content in every direction. Artboards are EPHEMERAL: nothing on the canvas is law, ever. 3. **Pick/mix (user).** Canvas/WYSIWYG edits welcome. 4. **Graduate (ours) — the step that makes this safe.** The keeper is CONVERTED into the design app, not copied: a numbered sketch in the flow's `sketches/` importing the studio's `shared.css`, every hard-coded artboard value replaced with real tokens, registered in `sketches.ts`, and the lock appended to `decisions.md`. Un-graduated artboards may be discarded freely; a decision that only exists on a canvas does not exist. 5. **Build (ours).** Primitives and screens land in the app as always; a screen needing more iteration keeps cycling as a studio sketch. **Hard rules:** - `/design-sync` is PULL-ONLY. Never let the canvas push components or tokens into a repo: `theme-source.ts` is the token source of truth and components flow OUT of the UI package, never in from a canvas. - Graduated sketches go through the same verify pass as any sketch (design-verify / impeccable) — graduation is conversion + verification, not a rename. - Anything user-facing built from an artboard still follows the repo's HARD-RULES.md and device-pass obligations; the artboard is a sketch of intent, not a spec of record. ## The Exploration Program (multi-round method for big surfaces) For any surface bigger than one component (a chat system, a new tab, a redesign), do NOT one-shot full screens. Run the program: 1. **Order the decisions by dependency** — shell/container first, then the typography/turn system, then component families, then composites, then states, then satellite surfaces. Publish the order as a board so the user sees what locks when. 2. **Per round: 3–4 GENUINELY different directions** — vary register/material/density, not shades of one idea. Same content rendered in every direction so comparison is honest. Light AND dark for every variant. Flag your pick with one-line reasoning; honest cons on every option (including the pick). 3. **The user picks or mixes; picks become law** — append the lock to the flow's `decisions.md` immediately, then design the next round *inside* the locked constraints. Constraints compound; that's where the taste comes from. 4. **Go piece by piece** — when a round is still too big (a header, a composer), explode it into pieces and explore each piece's variants separately. 5. **Artifacts, not spec-cards.** Records/data render as crafted artifacts native to the brand's material world; conversational text stays plain typography. Never default to uniform rounded-rect "AI dashboard" cards. ## Studio sketch conventions (the deliverable format) - Boards are **self-contained HTML** in the flow's `sketches/` dir, importing the studio's `shared.css` for real tokens. Register every board in the flow's `sketches.ts` manifest and run the design app's `check-types` after. - Boards must be **interactive where the decision is about behavior**: scroll demos, replay buttons, working inputs, tappable state machines. Motion IS spec — show it, don't describe it. - Every variant in **light + dark**. Respect `prefers-reduced-motion` in every animation. - Version per decision: new numbered file per iteration, never overwrite history; the flow's `decisions.md` records what each round locked. ## Drift protocol (when this skill disagrees with reality) When repo reality contradicts this skill or an app pack (paths, commands, tokens, components): 1. **Log it** the moment you notice: append to the app's drift file (golf: `apps/design/.skill-drift.md`) with date + what's wrong + what reality is. 2. **Feed Skill Watch**: also let `skill-watch` record the deviation. If it is structural drift, update the source skill at `~/repos/bokendell/skills-marketplace` in the same session (leave changes uncommitted for review) — or explicitly offer if mid-task. 3. **Never silently work around drift** — that's how the next session inherits the bug. ## Mock-First Decisions (THE META-RULE) **When you need the user to decide between options, build a visual comparison instead of asking a text question.** This applies to this skill and to any skill that delegates decisions through it (`dev-research`, `dev-plan`, `superpowers:brainstorming`, the built-in brainstorming flow inside this skill, etc.). The rule, in order of preference: 1. **UI decisions → HTML mock showcase with options side-by-side.** Generate a self-contained HTML file with each option as a fully-styled variant using the real app tokens (OKLch colors, actual fonts via Google Fonts CDN, realistic scenario content — actual course names, player names, score values from the domain). Annotate each option with Pro/Con trade-offs so the user can compare quickly. Never describe a layout in prose when you can show it. 2. **Backend / architecture / data-flow decisions → Mermaid diagram.** Draw the options as flowcharts, sequence diagrams, ERDs, or state diagrams. Inline them in the message or in an HTML file that renders Mermaid via the CDN. Show the trade-offs visually — which nodes differ, which arrows flip, which tables appear in Option A but not Option B. 3. **Decision-tree / branching options → comparison table.** Multi-axis choices (e.g. "which game types × which players × which scoring mode") should be rendered as a matrix with checkmarks/X's, not a prose list. 4. **Only fall back to plain text questions when the decision is truly abstract** — tone of voice, naming, yes/no confirms, priority ordering. Never for layout, color, component choice, data flow, schema shape, or flow ordering. ### How to apply it - Before asking any clarifying question, ask yourself: "could I show this instead of saying it?" If yes, build the mock. - Generating a mock is cheaper than spending 3 turns clarifying a misunderstanding. Assume text will be misread. - Use the real token values so mocks look like the app, not a generic preview. Inline them as CSS custom properties at the top of the HTML file, read from the repo's `DESIGN.md` frontmatter (or `packages/tokens/src/theme-source.ts` where no DESIGN.md exists yet) — never from memory or from a second-hand list. - Realistic scenario data: actual course names (Torrey Pines, Pebble Beach), real game types (Nassau, Skins), realistic player names and scores. Never "User A / User B / Player 1". - Each option gets a Pro/Con block. The user should be able to pick in <30s per comparison. - **Verify physical space before including elements.** For Dynamic Island / Lock Screen / native widget mocks, calculate the actual point budget: Dynamic Island Compact base = 126pt wide, camera cutout ~24pt, ~22pt padding → ~40pt per side slot. DM Mono at 16pt ≈ 9px/char. If a string overflows the slot, drop the unit or shorten the token, don't inflate the mock's dimensions to make it fit. Include a fit-verification note in the mock showing the math. ### Mock versioning + single persistent tunnel **File naming — version-per-decision, stored as history:** - Every decision point gets a numbered file: `docs/planning//mocks/NN-.html` - Every **iteration on the same decision** (user gives feedback, you refine) gets its own numbered file too: `NN--v2.html`, `NN--v3.html`, or just increments the NN prefix if the iteration is substantial enough to feel like a new decision. Never silently overwrite a previous iteration — the file history IS the decision log. - Example real history: - `mocks/01-compact-state.html` — first comparison, 3 variants - `mocks/02-variant-a-refined.html` — refinement on the picked variant - `mocks/03-refined-decluttered.html` — response to "too cluttered" feedback - The user should be able to scroll through the folder later and reconstruct why a choice was made, in order. **Also maintain a `current.html` pointer** in the same folder — always a copy of the newest iteration. This is what the persistent tunnel serves. **Single persistent tunnel per initiative (not per mock):** The user only ever looks at one mock at a time. Don't spin up a new tunnel for each iteration — that leaves orphans, burns cache, and forces the user to track multiple URLs. Instead: 1. On the **first** mock of an initiative, generate the numbered file AND copy it to `current.html` in the same folder. 2. Start ONE tunnel serving `current.html`: ```bash bash .claude/skills/remote-preview/scripts/host.sh \ docs/planning//mocks/current.html \ -mock ``` 3. Hand the user the single stable URL: `https://.trycloudflare.com/current.html`. This URL stays the same for the whole initiative. 4. On **every subsequent iteration**, write the new numbered file, then `cp .html current.html` to swap the served content. The user refreshes the same URL and sees the new version. 5. Tear the tunnel down with `stop.sh -mock` at the end of the decision session (end of the initiative or when the user says they're done reviewing). 6. **Do not create additional tunnels** for later decisions in the same initiative — keep reusing the same one. If the decision topic changes dramatically, you can write a new numbered file and still copy it to the same `current.html`. This gives the user: one bookmarkable URL, full version history on disk, no tunnel proliferation, and the ability to scroll back through the numbered files after the fact. ### Sharing the mock with the user Once the mock is written, **do not silently open it or silently tunnel it**. Ask how they want to review: > "Mock saved to ``. How do you want to review it? > 1. **Open locally** in your desktop browser (`open `) > 2. **Host on a tunnel** so you can view from your phone — uses `remote-preview` skill (I'll reuse the existing initiative tunnel if one's already up, or start a fresh one if not) > 3. **Both** > 4. **Skip** — I'll describe it here" Rules: - Never silently `open` a file or silently start a tunnel. Always ask first. - If a persistent tunnel already exists for this initiative (check `bash .claude/skills/remote-preview/scripts/list.sh` for a label matching `-mock`), **reuse it** — `cp .html current.html` and tell the user to refresh the existing URL. Do not start a second tunnel. - If no initiative tunnel exists, start one following the single-persistent-tunnel protocol above. - At the end of the decision session (user says "we're done with mocks" or the initiative moves to implementation), tear the tunnel down with `stop.sh