11 KiB
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.cssextension tailwind.configorpostcss.configpresent in project roottokens/,theme/, ordesign-system/directory exists- Storybook config (
.storybook/) present - Animation lib in
package.jsondeps: any packageis_anim_lib_installedrecognizes (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: enable design) then /reload-plugins- source=local or default →
profile.sh set web(orenable design), then/reload-plugins. - source=flag (the conversation runs under
claude --settings, frozen) → relaunch it with a design profile:cc <name> web. - the
21stCLI 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 runnpm i -g @21st-dev/clithen21st login(no API key, no MCP). - Do NOT hand-activate individual tools. Packs are the unit of activation.
- source=local or default →
-
12 /
SIGN-IN REQUIRED→ STOP. The 21st CLI is installed but21st whoamireports 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 run21st loginin 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-rundesign-tool-gate.shbefore any 21st step:READY→ continue; still12→ ask again once, then offer the opt-out. Explicit refusal — the user answers "proceed without 21st" (or words to that effect) → say visibly21st skipped for this run at your requestand continue with the rest of the toolchain, 21st steps left out; after that, a later12in 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 run21st loginyourself — it opens a browser and needs the human.TWENTYFIRST_TOKENis a shell-profile setting followed by a session restart, never an in-sessionexport(tool calls don't share a shell, and a secret doesn't belong in the transcript). -
11 /
READY BUT UNVERIFIED→21st whoamicould 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:
- Motion signal — the task matched a motion keyword from §DETECTION:
animation,transition,hover,motion, oranimate. A static button / card / layout with no motion signal needs no anim lib → skip. - Stack eligible —
detect_anim_eligibilityreturnseligible|…. - No anim lib yet —
is_anim_lib_installedfinds 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 + existingpackage.json= consent required — same contract as/onboardSTEP 2.5, opposite of/init-projectSTEP 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 skilldesign-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
initunprompted: 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 design/reload-plugins, orcc <name> webunder a flag), never an atomic tool toggle —current --plainis the single source of what's active.
- the
21stCLI 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=indesign-tool-gate.sh— edit there to add/remove a blocking pack or plugin. - The gate makes no
claudecall; it runsprofile.sh current --plainand21st whoami. Trivial / non-design tasks skip it entirely. - The 21st sign-in state is gate-only:
profile.shhas no counterpart. - Do NOT run this gate on pure backend/API/CLI tasks (no signals = no gate).