Files
claude/lib/design-gate.md
T

209 lines
11 KiB
Markdown

# 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 <pack | plugin id>` per entry listed as off, then `/reload-plugins`.
- **source=flag** (the conversation runs under `claude --settings`, frozen)
→ relaunch it with a design profile: `cc <name> 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>|<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` (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 <pack>`
+ `/reload-plugins`, or `cc <name> 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).