impeccable

name	impeccable
description	Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
od	{"mode":"design-system","surface":"web","platform":"desktop","category":"creative-direction","upstream":"https://github.com/pbakaus/impeccable","preview":{"type":"html"},"craft":{"requires":["anti-ai-slop","typography","color","animation-discipline","accessibility-baseline"]},"design_system":{"requires":false,"generates":true,"sections":["visual-theme","color","typography","spacing","layout","components","motion","voice","anti-patterns"]},"critique":{"policy":"opt-in","threshold":4,"max_rounds":3,"fallback":"ship_best","pre_gate":{"linter":"scripts/lint-artifact.mjs","blocks_on":["P0","P1"]},"panelists":{"designer":0,"critic":0.4,"brand":0.2,"a11y":0.2,"copy":0.2}},"inputs":[{"name":"target","type":"string","required":false,"description":"File, route, component, or URL to work on. Omit for the command menu."}],"outputs":{"primary":"edited frontend source (or a critique report for evaluate commands)"},"evals":"evals/"}

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:

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:

{
  "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 or 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:

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

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.

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):

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.