---
id: joewinke/jat/impeccable
version: "b3187e50"
license: MIT
install: manual
updated: 2026-07-27
---

# impeccable — impeccable shapes production frontend interfaces through design iteration, critique, and craft. It handles everything from visual hierarchy and accessibility to responsive layouts, design systems, and micro-interactions—grounded in project context via PRODUCT.md and DESIGN.md. Real working code, committed design choices.

Publisher: joewinke · Stars: 248 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/joewinke/jat`

## SKILL.md

Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.

## Setup (non-optional)

Two steps before any design work. Both are required. Skipping either produces generic output that ignores the project.

### 1. Context gathering

Two files, case-insensitive, found at the project root or a conventional docs location (`docs/`, `ide/docs/`):

- **PRODUCT.md** — required. Users, brand, tone, anti-references, strategic principles.
- **DESIGN.md** — optional, strongly recommended. Colors, typography, elevation, components.

Load both in one call:

```bash
node .agents/skills/impeccable/scripts/load-context.mjs
```

Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`.

The JSON also carries the **host theming rule**:

- `themeRule` — the project's color discipline (e.g. token-only, no hex/oklch/rgb literals). When present, treat it as a hard constraint on every design command: obey it exactly, and grep your diff for raw `#`/`rgb(`/`oklch(` literals before declaring done.
- `tokenSource` — where the token source lives (e.g. `src/app.css`). Point every new color at this file; never inline a one-off hue.

Both are `null` for projects with no token system (a static artifact, a one-off HTML poster) — there, color literals are allowed.

**Per-project overrides.** Drop an optional `.impeccable.json` at the project root to steer the loader:

```json
{
  "designPath": "ide/docs/DESIGN.md",
  "productPath": "PRODUCT.md",
  "themeRule": "Token-only: use theme tokens, never a raw hue.",
  "tokenSource": "src/app.css"
}
```

Every field is optional; omit what auto-discovery already gets right. `designPath`/`productPath` override discovery when a project keeps those files off the repo root (JAT's DESIGN.md lives at `ide/docs/DESIGN.md`). `themeRule`/`tokenSource` override the auto-detected token-only rule.

If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `$impeccable teach` or `$impeccable document` (they rewrite the files), or the user manually edited one.

`$impeccable live` already warms context via `live.mjs` — if you've run `live.mjs`, don't also run `load-context.mjs` this session.

If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `$impeccable teach`, then resume the user's original task with the fresh context.

If DESIGN.md is missing: nudge once per session (_"Run `$impeccable document` for more on-brand output"_), then proceed.

### 2. Register

Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio — design IS the product) or **product** (app UI, admin, dashboard, tool — design SERVES the product).

Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins.

If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `$impeccable teach` to add the field explicitly.

Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both.

## Shared design laws

Apply to every design, both registers. Match implementation complexity to the aesthetic vision — maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. The model is capable of extraordinary work — don't hold back.

### Craft is required by reference, not restated here

The universal, cross-repo doctrine — OKLCH discipline, never `#000`/`#fff`, contrast minimums, the type scale ratio, line length, ease-out curves, don't-animate-layout, and the full **absolute ban** list (side-stripe borders, gradient text, decorative glassmorphism, the hero-metric template, identical card grids, modal-first, hardcoded indigo accent, two-stop trust gradients, emoji-as-icons) — lives in the **one canonical craft layer**, not in this skill. This skill used to be one of three drifting copies of those laws; it now requires them from its frontmatter:

```yaml
od:
  craft:
    requires: [anti-ai-slop, typography, color, animation-discipline, accessibility-baseline]
```

→ **`~/code/jat/shared/craft/`** (`anti-ai-slop.md`, `color.md`, `typography.md`, `animation-discipline.md`, `accessibility-baseline.md`) is the source. Read them when a design decision touches color, type, motion, or the bans. They are match-and-refuse: if you're about to write a banned element, rewrite it with different structure. Cross-register failures are those bans; register-specific failures live in each reference.

What follows is the doctrine **unique to impeccable** — the parts craft does not cover.

### Color strategy — commit before you pick

Pick a **color strategy** before picking colors. Four steps on the commitment axis:

- **Restrained** — tinted neutrals + one accent ≤10%. Product default; brand minimalism.
- **Committed** — one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
- **Full palette** — 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
- **Drenched** — the surface IS the color. Brand heroes, campaign pages.

The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex. (The OKLCH mechanics and neutral-tinting rules this strategy uses are in `craft/color.md`.)

### Theme — run the scene sentence, not the category

Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe."

Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough — add detail until it does.

"Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category.

### Layout — impeccable's structural bans

- Vary spacing for rhythm. Same padding everywhere is monotony.
- Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
- Don't wrap everything in a container. Most things don't need one.

### Copy

- Every word earns its place. No restated headings, no intros that repeat the title.
- **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`.

### The AI slop test

If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.

**Category-reflex check.** If someone could guess the theme and palette from the category name alone — "observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black" — it's the training-data reflex. Rework the scene sentence and color strategy until the answer is no longer obvious from the domain.

## Commands

| Command              | Category | Description                                                                                                     | Reference                                        |
| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `craft [feature]`    | Build    | Shape, then build a feature end-to-end                                                                          | [reference/craft.md](reference/craft.md)         |
| `shape [feature]`    | Build    | Plan UX/UI before writing code                                                                                  | [reference/shape.md](reference/shape.md)         |
| `teach`              | Build    | Set up PRODUCT.md and DESIGN.md context                                                                         | [reference/teach.md](reference/teach.md)         |
| `document`           | Build    | Generate DESIGN.md from existing project code                                                                   | [reference/document.md](reference/document.md)   |
| `extract [target]`   | Build    | Pull reusable tokens and components into design system                                                          | [reference/extract.md](reference/extract.md)     |
| `critique [target]`  | Evaluate | UX design review with heuristic scoring                                                                         | [reference/critique.md](reference/critique.md)   |
| `audit [target]`     | Evaluate | Technical quality checks (a11y, perf, responsive)                                                               | [reference/audit.md](reference/audit.md)         |
| `polish [target]`    | Refine   | Final quality pass before shipping                                                                              | [reference/polish.md](reference/polish.md)       |
| `bolder [target]`    | Refine   | Amplify safe or bland designs                                                                                   | [reference/bolder.md](reference/bolder.md)       |
| `quieter [target]`   | Refine   | Tone down aggressive or overstimulating designs                                                                 | [reference/quieter.md](reference/quieter.md)     |
| `distill [target]`   | Refine   | Strip to essence, remove complexity                                                                             | [reference/distill.md](reference/distill.md)     |
| `harden [target]`    | Refine   | Production-ready: errors, i18n, edge cases                                                                      | [reference/harden.md](reference/harden.md)       |
| `onboard [target]`   | Refine   | Design first-run flows, empty states, activation                                                                | [reference/onboard.md](reference/onboard.md)     |
| `animate [target]`   | Enhance  | Add purposeful animations and motion                                                                            | [reference/animate.md](reference/animate.md)     |
| `colorize [target]`  | Enhance  | Add strategic color to monochromatic UIs                                                                        | [reference/colorize.md](reference/colorize.md)   |
| `typeset [target]`   | Enhance  | Improve typography hierarchy and fonts                                                                          | [reference/typeset.md](reference/typeset.md)     |
| `layout [target]`    | Enhance  | Fix spacing, rhythm, and visual hierarchy                                                                       | [reference/layout.md](reference/layout.md)       |
| `delight [target]`   | Enhance  | Add personality and memorable touches                                                                           | [reference/delight.md](reference/delight.md)     |
| `overdrive [target]` | Enhance  | Push past conventional limits                                                                                   | [reference/overdrive.md](reference/overdrive.md) |
| `clarify [target]`   | Fix      | Improve UX copy, labels, and error messages                                                                     | [reference/clarify.md](reference/clarify.md)     |
| `adapt [target]`     | Fix      | Adapt for different devices and screen sizes                                                                    | [reference/adapt.md](reference/adapt.md)         |
| `optimize [target]`  | Fix      | Diagnose and fix UI performance                                                                                 | [reference/optimize.md](reference/optimize.md)   |
| `live`               | Iterate  | Visual variant mode: pick elements in the browser, generate alternatives                                        | [reference/live.md](reference/live.md)           |
| `pipeline`           | Plan     | Full setup protocol: teach → document → create all 6 passes as JAT tasks with wired deps. One command, turnkey. | [reference/pipeline.md](reference/pipeline.md)   |

Plus two management commands — `pin <command>` and `unpin <command>`, detailed below.

### Routing rules

1. **No argument** — render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
2. **First word matches a command** — load its reference file and follow its instructions. Everything after the command name is the target.
3. **First word doesn't match** — general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.

Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `$impeccable`.

## Pin / Unpin

**Pin** creates a standalone shortcut so `$<command>` invokes `$impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.

```bash
node .agents/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
```

Valid `<command>` is any command from the table above. Report the script's result concisely — confirm the new shortcut on success, relay stderr verbatim on error.

## Evals

The highest-traffic commands (`craft`, `critique`, `polish`) ship prompt +
natural-language-assertion fixtures under `evals/`, in Open Design's
`evals.json` shape. A single dependency-free runner grades them against a cheap
model via the JAT relay (never a cloud API):

```bash
node .agents/skills/impeccable/evals/run.mjs            # run all fixtures
node .agents/skills/impeccable/evals/run.mjs critique   # one fixture
node .agents/skills/impeccable/evals/run.mjs --dry-run  # validate shape only, no inference
```

Assertions are prose judged by a cheap grader model, not regex. Without a relay,
the runner still validates every fixture's shape (a cheap CI gate). See
`evals/README.md`.


[View on SkillFed](https://skillfed.io/joewinke/jat/impeccable) · [View on GitHub](https://github.com/joewinke/jat)