claude_mac/lib/design-gate.md

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 for activation is the profile system — never an atomic per-tool toggle. The gate's whole job: confirm the design toolchain is active, and if not, point at ONE command — /profile design.

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 draws from the one design profile — so the gate checks that profile's design-core tools (the # GATE-BLOCK: allowlist in design.profile: ui-ux-pro-max, frontend-design, emil-design-eng, design-motion-principles, design-html, design-review, design-consultation, the 21st CLI and 21st-ui-build — the canary for the whole 21st skill pack). The profile also bundles browser/plan/shotgun tooling and graphify for convenience; those never trip the gate. Motion (design-motion-principles) and static-HTML (design-html) are already in the core set — checked regardless; their CLAUDE.md "+motion / +static" notes say which tool you'll lean on, not a separate activation step. site-motion (personal skill, site-level scroll/page choreography) rides the same Build chain but isn't on the GATE-BLOCK list: 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 reads the design-core tools (# GATE-BLOCK: in design.profile) plus their types (profile.sh show design --plain) and checks each on its own channel — skill symlink, claude plugin list, claude mcp list, command -v. It never reads disabledMcpServers (unreliable for bi-modal servers like context7). The core set lives in design.profile, not in the script or here — single source.

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 reports up to three groups; relay them and the remedy to the user:

  🎨 DESIGN DETECTED — the design toolchain isn't fully active.
  activate with /profile design:        <skills / ui-ux-pro-max>
  required + manual step:                <e.g. 21st — needs the CLI>
  → run  /profile design  to activate it, then continue.
  

  • activate with /profile design → skills + the plugin; /profile design turns them on directly.
  • required + manual step → required tools the profile can't flip silently. the 21st CLI lands here: it TRIPS the gate (it's required for Build), it is NOT a silent "optional". /profile design symlinks the 21st skills, but the CLI they shell out to is a global npm install: 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. The profile is 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 → claude was unreachable, so the design plugin (ui-ux-pro-max) could NOT be checked. Do NOT report a plain "ready": proceed only after telling the user that N tool(s) went unverified and having them confirm with claude plugin list. Fail-visible, not fail-silent. A 21st (whoami: rc=… …) entry in this block means the CLI itself could not answer (a runtime/PATH problem, e.g. node under nvm) — the remedy is the diagnostic the script prints, never a sign-in prompt; relay its own line.

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 ran /profile design, or after the sign-in re-run returns READY). Never on the INCOMPLETE stop path — that path has one action only (/profile design); 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>|<package>|<reason>'
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 (<reason>), no anim lib — `<cmd>`? (optional; say the word, I'll add it)

Rules:

• Suggest-only, never auto-install. Run <cmd> 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 (# GATE-BLOCK: core set, §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 BOTH hold — else stay silent:

1. impeccable symlink present under skills/ (non-blocking external — not on the # GATE-BLOCK: list, so §3 never checks it).
2. The project has no PRODUCT.md at its root.

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 defaults to the design profile. A task needing another profile's toolchain passes it: design-tool-gate.sh <profile>. Scope comes from that profile's # GATE-BLOCK: line (absent → every skill/plugin/mcp entry). The remedy is always /profile <that> — a profile, never a lone tool.

IMPORTANT

• Remedy is ALWAYS a profile (/profile design), never an atomic tool toggle — the profile system is the single source of truth for what's active.
• the 21st CLI is REQUIRED (it trips the gate) and /profile design cannot 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 design-core set (what trips the gate) is declared in design.profile on the # GATE-BLOCK: line(s) — edit there to add/remove a blocking design tool, not in the script.
• The state check shells out to claude (plugin/mcp list): a few seconds. Trivial / non-design tasks skip it entirely (no signal, or trivial tier).
• design-tool-gate.sh's per-type state checks MIRROR profile.sh:skill_status() — change one, sync the other, except the 21st auth state: gate-only, no skill_status counterpart.
• Do NOT run this gate on pure backend/API/CLI tasks (no signals = no gate).