Impeccable

---
name: impeccable
description: Design, shape, critique, audit, and polish frontend UI; writes docs/DESIGN-BRIEF.md for stack handoff. Use for UI/UX design work or when invoking /impeccable.
---


## STOP - Read before ANY tool call

1. Read `{{GUARDRAILS_PATH}}`
2. Read `_shared/sdd-artifacts/SESSION.md`; load session-state for `$Cwd`
3. If the relevant gate is not approved: **STOP** - ask user **(pt-BR)** - do **NOT** Write/Shell
4. SDD/develop skills: after **ONE** step/task, **STOP** session - handoff only
5. This skill body is **English**; user-facing prompts may be **(pt-BR)**

### Step -1 - Gate check (report in chat before continuing)

```
Gate check:
[ ] guardrails.mdc read
[ ] SESSION.md read; session-state loaded
[ ] User confirmed current action (sim)
-> If any unchecked: STOP
```

---

Inspired by [pbakaus/impeccable](https://github.com/pbakaus/impeccable) — this skill is a **partial toolkit harness**, not a full port. See `docs/CREDITS.md`.

## Trigger

Use when user asks for `/impeccable`, `/impeccable`, or any Impeccable command (`shape`, `audit`, `polish`, `craft`, etc.).

**Invocation forms:**

| User says | Behavior |
|-----------|----------|
| `/impeccable` | Context-aware menu; no auto-run |
| `/impeccable <command> [target]` | Load `reference/<command>.md` and execute |
| `/impeccable-shape` | Alias: `shape` command |
| `/impeccable-audit` | Alias: `audit` command |

## Outcome

Production-grade UI design artifacts and/or code per upstream Impeccable command flow. `shape`/`craft` shape phase writes `docs/DESIGN-BRIEF.md` after user confirmation.

## Lazy-load (mandatory per command)

| When | Path (after syncing the active adapter) |
|------|--------------------------------|
| Any sub-command | `{{TOOLKIT_ROOT}}/skills/impeccable/reference/<command>.md` - **required before acting** |
| Register | `reference/brand.md` or `reference/product.md` per routing rules below |
| DESIGN-BRIEF contract | `{{TOOLKIT_ROOT}}/skills/impeccable/reference/DESIGN-BRIEF-TEMPLATE.md` |
| Hooks / live install | `reference/hooks.md` + `docs/impeccable-integration.md` |
| Integration docs | `docs/impeccable-integration.md` in toolkit repo |

Do **not** preload all 28 references. Load only the command reference + register for the current task.

**Never by default:** do not glob `reference/**` or preload every command file at session start.

**Progressive load (index-then-fanout):** (1) `PRODUCT.md` / setup context, (2) `reference/<command>.md` for the active command, (3) register (`brand.md` **or** `product.md` — not both unless routing requires), (4) fan-out to `DESIGN-BRIEF-TEMPLATE.md` / `hooks.md` / integration docs only when that command needs them.

## Setup (every session, before commands)

1. **Project context:** Read `PRODUCT.md` from workspace root (or monorepo target path). If missing -> **STOP** and run `init` flow (`reference/init.md`) before any other command.
2. If `DESIGN.md` exists, read it. If the user named a target path in a monorepo, scope context to that path.
3. **Sub-command:** If the user invoked a command (`craft`, `shape`, `audit`, …), read `reference/<command>.md` next. Non-optional.
4. **Code familiarity:** Read at least one project UI file (CSS/tokens/theme/representative component).
5. **Register (non-optional):** Marketing/landing/portfolio -> `reference/brand.md`. App UI/dashboard/tool -> `reference/product.md`. Use task cue, then surface in focus, then `register` in PRODUCT.md.
6. **New project palette:** If no committed brand colors in tokens, compose OKLCH palette per register refs. Skip if existing tokens define brand colors.

## Design guidance (summary - full rules in references)

Produce production-grade code and design choices. Match-and-refuse absolute bans:

- Side-stripe borders, gradient text, glassmorphism as default
- Hero-metric template, identical card grids, eyebrow on every section
- Numbered section markers (01/02/03) as default scaffolding
- Text overflow at breakpoints; cream/sand/beige body backgrounds (OKLCH warm-neutral band)
- Near-black + single acid-green / vermilion accent as an unearned default (same cluster family as cream+serif+terracotta and broadsheet-hairline layouts)
- Overused fonts (Inter as default); bounce/elastic easing; `transition-all` reflex
- Cards as lazy default; nested cards always wrong
- Image hover transforms (Tailwind group-hover on images)

**Signature:** Spend boldness once. Name one memorable motif that carries the brief; keep surroundings quiet. Cut decoration that does not serve that motif (Chanel cut).

**Hero as thesis:** Open with the most characteristic thing in the subject's world (headline, image, motion, live demo)—not a generic metric strip unless that *is* the product story.

**Typography:** body ≤65-75ch; display clamp max ≤6rem; letter-spacing floor ≥-0.04em on display headings.

**Motion:** ease-out-quart/quint/expo; `@media (prefers-reduced-motion: reduce)` on every animation. Prefer one orchestrated moment over scattered effects.

**Color:** OKLCH; verify contrast (4.5:1 body, 3:1 large); pick color strategy (Restrained / Committed / Full palette / Drenched) before picking colors.

**Slop test:** If someone could say "AI made that" without doubt, it failed. Run first-order and second-order category-reflex checks (see register refs).

**External note:** Anthropic `frontend-design` is optional inspiration only—not a Core sibling. See `docs/CREDITS.md`. Canonical path remains impeccable → DESIGN-BRIEF → `*-developer`.

## Commands

| Command | Category | Reference |
|---------|----------|-----------|
| `init` | Build | `reference/init.md` |
| `shape [feature]` | Build | `reference/shape.md` |
| `craft [feature]` | Build | `reference/craft.md` |
| `document` | Build | `reference/document.md` — Impeccable `DESIGN.md` from UI code. Not `document-plan` / `document-implement`. |
| `extract [target]` | Build | `reference/extract.md` |
| `critique [target]` | Evaluate | `reference/critique.md` |
| `audit [target]` | Evaluate | `reference/audit.md` |
| `polish [target]` | Refine | `reference/polish.md` |
| `harden [target]` | Refine | `reference/harden.md` |
| `onboard [target]` | Refine | `reference/onboard.md` |
| `animate` | Enhance | `reference/animate.md` |
| `colorize` | Enhance | `reference/colorize.md` |
| `typeset` | Enhance | `reference/typeset.md` |
| `layout` | Enhance | `reference/layout.md` |
| `bolder` | Refine | `reference/bolder.md` |
| `quieter` | Refine | `reference/quieter.md` |
| `distill` | Refine | `reference/distill.md` |
| `delight` | Enhance | `reference/delight.md` |
| `overdrive` | Enhance | `reference/overdrive.md` |
| `clarify` | Fix | `reference/clarify.md` |
| `adapt` | Fix | `reference/adapt.md` |
| `optimize` | Fix | `reference/optimize.md` |
| `live` | Iterate | requires per-project install (see below). Reference is not vendored. |
| `hooks` | Manage | `reference/hooks.md` - requires per-project install |

Also load, one file at a time, when that step is the task: `reference/craft-floor.md` (quality floor before UI edits), `reference/routing.md` (no-command menu), `reference/new-work.md` (new surface), `reference/operate.md` (app/docs reading). `teach` is a deprecated alias for `init`.

**Harness wins over vendored text.** These playbooks are adapted from [pbakaus/impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0). They still mention `{{scripts_path}}/impeccable` and `impeccable context`. This toolkit does not ship that launcher, `skill/scripts/bin`, `font-index.json`, or `browser-bundle`. If a vendored line asks for the launcher:

- `detect` → `npx impeccable detect --json` (no `npx impeccable install`)
- concept-seed, surface-brief, build-phase, comp-spec, embed-prompt, generate-image → do not run; shape still ends in `docs/DESIGN-BRIEF.md`
- live, hooks, install → stop and ask **sim** as in the install section below

`agents/` holds four upstream finish helpers. They are not the SDD roster in `_shared/agents/`. Do not spawn them for spec, plan, or develop. Spawn only when the user asked for that impeccable step, and never past a missing **sim**.

## Routing rules

1. **No command argument:** Context-aware menu. If `PRODUCT.md` missing, you are in `init`. Otherwise recommend 2-3 commands with one-line reasons, then full menu. Never auto-run.
2. **First word matches a command:** Load its reference and follow it. Remainder is the target.
3. **Intent maps clearly to one command** (e.g. "fix spacing" -> `layout`): load that reference. Ask once if ambiguous.
4. **No clear match:** Apply setup, general rules, and register reference.

## Detector bridge (`audit`, optional pre-`polish`)

When `reference/audit.md` calls for detector output, run:

```bash
npx impeccable detect --json <paths>
```

- No project install required; `npx` fetches the npm package transiently.
- This harness does not ship `scripts/detect.mjs`, `scripts/critique-storage.mjs`, or `scripts/live-server.mjs`. Critique and polish use `npx impeccable detect` for the scan and skip local snapshot or overlay scripts.
- Requires Node/npm and `write_confirmed` / shell gate approval.
- Fold JSON hits into the audit report per `audit.md` scoring (5 dimensions, P0-P3).

If `npx` fails, continue with manual audit per reference; note detector was skipped.

## Per-project install (live, design hook) - never automatic

`npx impeccable install` writes `.cursor/hooks.json`, `.impeccable/`, and local skill copy. **Violates toolkit guardrails if run without explicit user consent.**

When user requests `live` or design hook:

1. **STOP** - ask user **(pt-BR):** *"Isso exige `npx impeccable install` neste projeto (grava `.cursor/hooks.json` e `.impeccable/`). Posso rodar? (sim / não)"*
2. Only after **sim** -> Shell with install.
3. Document hook coexistence: merge with toolkit hooks per `docs/HOOKS.md` and `docs/impeccable-integration.md`.

## DESIGN-BRIEF handoff (shape / craft)

After user **confirms** the design brief:

1. Write `docs/DESIGN-BRIEF.md` using `reference/DESIGN-BRIEF-TEMPLATE.md` (stack-neutral sections 1-10).
2. Set `target_stack` from workspace detection or user input.
3. For **Blip plugins** (`blip-ds` in `package.json`): document BDS components, iframe constraints, and Lite vs Full profile notes in brief **section 9**; implementation uses `react-developer` + `blip-guidelines/`.
4. **STOP session** - one session = design OR implementation, not both.
5. Ask user **(pt-BR):** *"Brief salvo. Inicie nova conversa com `/<stack>-developer` para implementar."*

| `target_stack` | Next skill |
|----------------|------------|
| `react` | `/react-developer` |
| `react-native` | `/react-native-developer` |
| `angular` | `/angular-developer` |
| `vue` | `/vue-developer` |
| `blazor` | `/blazor-developer` |
| `electron` | `/electron-developer` |
| `html-css` / vanilla | `/javascript-developer` |
| ambiguous | `/developer` (router) |

SDD composability: `shape` may also feed PRD sections when user is in SDD flow; prefer `DESIGN-BRIEF.md` for frontend handoff.

## SDD session rule

One invocation = one Impeccable command outcome. After `shape` brief is saved, or after `polish`/`audit` report, **STOP**. Do not continue to `react-developer` in the same session.

## Handoff

| Situation | Next |
|-----------|------|
| Brief confirmed | New session -> `react-developer` / `angular-developer` / `developer` |
| Large feature + PRD | `sdd-spec` -> `sdd-plan` -> `sdd-develop` |
| Commit design artifacts | `/commit` (user request only) |
| More Impeccable commands | New session -> `/impeccable <command>` |