209 lines
11 KiB
Markdown
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).
|