# DESIGN GATE — Auto-detect design tasks, ensure the design toolchain is active Inline snippet. Include in any agent STEP 0 that may touch UI/design. ## WHEN TO RUN Run this gate when the task description OR target files match design signals. ## DETECTION Check BOTH the task description AND the filesystem: **Task description signals** (case-insensitive match on $ARGUMENTS): - UI keywords: `component`, `button`, `card`, `modal`, `dialog`, `tooltip`, `dropdown`, `sidebar`, `navbar`, `header`, `footer`, `layout`, `grid`, `form`, `input`, `table` - Style keywords: `css`, `style`, `theme`, `color`, `font`, `spacing`, `margin`, `padding`, `border`, `shadow`, `animation`, `transition`, `hover`, `motion`, `animate`, `responsive`, `dark mode`, `light mode` - Design keywords: `design`, `ui`, `ux`, `visual`, `polish`, `pixel`, `figma`, `mockup`, `wireframe`, `prototype` - Framework UI: `tailwind`, `styled-component`, `emotion`, `chakra`, `radix`, `shadcn`, `headless` **Filesystem signals** (quick check, no deep scan): - Target files have `.tsx`, `.jsx`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.less`, or `.module.css` extension - `tailwind.config` or `postcss.config` present in project root - `tokens/`, `theme/`, or `design-system/` directory exists - Storybook config (`.storybook/`) present - Animation lib in `package.json` deps: any package `is_anim_lib_installed` recognizes (`lib/animation-lib-check.sh`, the single source) ## DECISION Source of truth is `profile.sh current --plain` (packs and managed plugins of THIS project and conversation) — never an atomic per-tool toggle. The gate's whole job: confirm the design toolchain is active, and if not, print ONE remedy line (see §3). ### 1. Tier — does the gate even apply? - **Trivial** (≤2 files, single cosmetic value, one CSS tweak — same scope as `/hotfix`) → no design tools required. Skip the gate, proceed. - **Build UI / design system / review-audit** → toolchain required, continue. - In doubt (trivial tweak vs real UI change) → do NOT silently skip: ask the user, or default to the Build tier. Tier does NOT change WHAT gets checked. Every non-trivial design tier needs the same required set, declared as `NEEDED=` in `lib/design-tool-gate.sh`: packs `design` and `gstack-design`, the `ui-ux-pro-max` plugin, and the `21st` CLI signed in. Other packs and browser/plan tooling never trip the gate. Motion and static-HTML skills ride inside those packs; the Design work section (`rules/web-building.md`) names them, not a separate activation step. `site-motion` (personal skill, site-level scroll/page choreography) rides the same Build chain but isn't required: it ships with the repo, nothing to install or verify. ### 2. State — run the deterministic check bash "$HOME/.claude/lib/design-tool-gate.sh" It runs `profile.sh current --plain` and checks the `NEEDED=` entries of the script (the single source of the required set), then `command -v 21st` and `21st whoami`. It makes no `claude` call. Exit codes: `0` = ready · `11` = ready-but-unverified (proceed, but surface it) · `10` = incomplete (gate trips) · `12` = sign-in required (21st installed, signed out) · `2` = error. ### 3. Branch on the result - **0 / `READY`** → proceed silently. Toolchain is active. - **10 / `INCOMPLETE`** → STOP. The script names what is off and prints the remedy; relay both to the user: design toolchain: INCOMPLETE off: pack-design plugin:ui-ux-pro-max@ui-ux-pro-max-skill → run: bash ~/.claude/lib/profile.sh set web or: bash ~/.claude/lib/profile.sh enable design or: bash ~/.claude/lib/profile.sh enable ui-ux-pro-max@ui-ux-pro-max-skill then /reload-plugins - **source=local or default** → `profile.sh set web`, or one `profile.sh enable ` per entry listed as off, then `/reload-plugins`. - **source=flag** (the conversation runs under `claude --settings`, frozen) → relaunch it with a design profile: `cc web`. - **the `21st` CLI TRIPS the gate** when absent (required for Build), it is NOT a silent "optional". It is a global npm install the profile cannot do: tell the user to run `npm i -g @21st-dev/cli` then `21st login` (no API key, no MCP). - Do NOT hand-activate individual tools. Packs are the unit of activation. - **12 / `SIGN-IN REQUIRED`** → STOP. The 21st CLI is installed but `21st whoami` reports signed out. Relay the script's block, then ask the user to run `! 21st login` (the `!` prefix runs it in this session, browser flow, saves a local token) — or run `21st login` in any terminal on this machine, then reply (the token is a local file; any terminal works, `!` in-session is just the convenient form). END THE TURN and wait. On the user's reply, re-run `design-tool-gate.sh` before any 21st step: `READY` → continue; still `12` → ask again once, then offer the opt-out. Explicit refusal — the user answers "proceed without 21st" (or words to that effect) → say visibly `21st skipped for this run at your request` and continue with the rest of the toolchain, 21st steps left out; after that, a later `12` in the same run is reported in one line, never re-asked. Never skip silently ("not logged in, so we don't use it" is the failure this branch closes). Never run `21st login` yourself — it opens a browser and needs the human. `TWENTYFIRST_TOKEN` is a shell-profile setting followed by a session restart, never an in-session `export` (tool calls don't share a shell, and a secret doesn't belong in the transcript). - **11 / `READY BUT UNVERIFIED`** → `21st whoami` could not answer (a runtime/PATH problem, e.g. node under nvm). Do NOT report a plain "ready": proceed only after telling the user, relaying the diagnostic the script prints (`whoami: rc=… …`). Never a sign-in prompt. Fail-visible, not fail-silent. ### 4. Animation library — suggest-only (fires only on a real motion signal) Orthogonal to the toolchain check above: §2-3 are about Claude's design TOOLS; this is about the PROJECT's runtime dep. Evaluate it only once the toolchain is resolved and you're actually proceeding with the build (READY, after the user applied the remedy, or after the sign-in re-run returns READY). Never on the INCOMPLETE stop path — that path has one action only (the remedy line); don't stack an optional note on it. **Fires only when ALL THREE hold** — drop any one → no suggestion, stay silent: 1. **Motion signal** — the task matched a motion keyword from §DETECTION: `animation`, `transition`, `hover`, `motion`, or `animate`. A static button / card / layout with no motion signal needs no anim lib → skip. 2. **Stack eligible** — `detect_anim_eligibility` returns `eligible|…`. 3. **No anim lib yet** — `is_anim_lib_installed` finds none. Only if condition 1 holds, run the helper for 2 and 3 — do NOT re-list packages here; the helper's `is_anim_lib_installed` is the single source of which libs count: source "$HOME/.claude/lib/animation-lib-check.sh" result=$(detect_anim_eligibility) # '||' status=$(echo "$result" | cut -d'|' -f1) pkg=$(echo "$result" | cut -d'|' -f2) reason=$(echo "$result" | cut -d'|' -f3) if [ "$status" = "eligible" ] && ! is_anim_lib_installed >/dev/null; then cmd=$(recommend_anim_install_cmd "$pkg") # pnpm/yarn/bun/npm per lockfile # → surface the one-line suggestion below. Do NOT run $cmd. fi **Surface — always this single line (non-blocking, suggest-only):** 🎬 Stack motion-eligible (), no anim lib — ``? (optional; say the word, I'll add it) **Rules:** - **Suggest-only, never auto-install.** Run `` ONLY on explicit user consent. BDR-005: mid-session + existing `package.json` = consent required — same contract as `/onboard` STEP 2.5, opposite of `/init-project` STEP 5e (auto-install on a just-validated fresh scaffold). - **Non-blocking.** Never halts the build; NOT a second gate. The toolchain stop (§3, exit 10) is the only STOP. Surface the line, keep going. - **Stateless dedup, by construction.** The suggestion is ALWAYS the single line above — no first-time-block / later-short split. That split would need session state the gate doesn't have, and a file marker would persist forever (per project, not per session). Determinism here comes from having nothing to remember, not from a behavioral "the agent recalls it" guard. Re-fire is one ignorable line, on a narrow population: condition 3 (`is_anim_lib_installed`, 10 libs incl gsap / react-spring / lottie) kills it the instant any anim lib lands, so only "eligible + pure-CSS + actively declined" ever sees it twice. - **Two "motion"s (agent-facing).** The lib `motion` (npm dep, this step) ≠ the skill `design-motion-principles` (inside the design packs, §2-3). The toolchain check handles the skill; this step handles the lib. Don't conflate them when talking to the user. ### 5. Impeccable design context — suggest-only (one check, one line) Same class as §4: a PROJECT-side prerequisite, not a tool. `impeccable` installs globally, but every one of its verbs reads a per-project `PRODUCT.md` that only `/impeccable init` writes. Without it the skill runs on invented context, which is worse than not running it — and nothing else in the process says so, because init has to happen in the agent chat, not in an installer. **Fires when** the project has no `PRODUCT.md` at its root, else stay silent. impeccable ships in the required design packs, so §3 has already guaranteed it is installed by the time this runs. Evaluate it on the same path as §4: after the toolchain resolves, never on the INCOMPLETE stop path. One line, non-blocking: 🧭 impeccable has no project context here (no PRODUCT.md) — run `/impeccable init` first? (optional) **Rules:** - Non-blocking, and never run `init` unprompted: it interviews the user about the product, so it needs their attention, not their absence. - One line per session at most. A refusal is an answer; do not re-ask inside the same task. - Skip entirely for a review/audit of a single component and for any non-UI work. This is for Build and design-system tiers. ### Other toolchains The script takes no argument: it checks the one design set (`NEEDED=`). A task needing another toolchain adds its own gate; the remedy stays a pack or profile, never a lone tool. ## IMPORTANT - Remedy is ALWAYS the printed line (`profile.sh set web` / `enable ` + `/reload-plugins`, or `cc web` under a flag), never an atomic tool toggle; `current --plain` is the single source of what's active. - the `21st` CLI is REQUIRED (it trips the gate) and no profile can install it — the gate names the two commands; surface them to the user. Signed out → exit 12: ask `! 21st login`, wait, re-run; explicit opt-out only, never a silent skip. - The required set (what trips the gate) is `NEEDED=` in `design-tool-gate.sh` — edit there to add/remove a blocking pack or plugin. - The gate makes no `claude` call; it runs `profile.sh current --plain` and `21st whoami`. Trivial / non-design tasks skip it entirely. - The 21st sign-in state is gate-only: `profile.sh` has no counterpart. - Do NOT run this gate on pure backend/API/CLI tasks (no signals = no gate).