# Table of Contents

- [Docs | Impeccable](#docs-impeccable)
- [impeccable | Impeccable](#impeccable-impeccable)
- [extract | Impeccable](#extract-impeccable)
- [shape | Impeccable](#shape-impeccable)
- [audit | Impeccable](#audit-impeccable)
- [critique | Impeccable](#critique-impeccable)
- [polish | Impeccable](#polish-impeccable)
- [quieter | Impeccable](#quieter-impeccable)
- [bolder | Impeccable](#bolder-impeccable)
- [distill | Impeccable](#distill-impeccable)
- [harden | Impeccable](#harden-impeccable)
- [colorize | Impeccable](#colorize-impeccable)
- [typeset | Impeccable](#typeset-impeccable)
- [onboard | Impeccable](#onboard-impeccable)
- [layout | Impeccable](#layout-impeccable)
- [overdrive | Impeccable](#overdrive-impeccable)
- [adapt | Impeccable](#adapt-impeccable)
- [optimize | Impeccable](#optimize-impeccable)
- [clarify | Impeccable](#clarify-impeccable)
- [live | Impeccable](#live-impeccable)
- [Design Context | Impeccable](#design-context-impeccable)
- [Config and ignores | Impeccable](#config-and-ignores-impeccable)
- [animate | Impeccable](#animate-impeccable)
- [Doctor | Impeccable](#doctor-impeccable)
- [Detector CLI | Impeccable](#detector-cli-impeccable)
- [delight | Impeccable](#delight-impeccable)
- [New work | Impeccable](#new-work-impeccable)
- [Design hooks | Impeccable](#design-hooks-impeccable)
- [document | Impeccable](#document-impeccable)
- [init | Impeccable](#init-impeccable)

---

# Docs | Impeccable

[Skip to content](https://impeccable.style/docs/#main)

1.  01Install`npx impeccable install`Run from the project root, then reload your agent.
2.  02Set context`/impeccable init`Create PRODUCT.md and DESIGN.md.
3.  03Try it`/impeccable polish the pricing page`Point it at a real page.

Full walkthrough: [Getting started](https://impeccable.style/tutorials/getting-started)
.

[Start a project/impeccable init](https://impeccable.style/docs/init)
[Polish a page/impeccable polish](https://impeccable.style/docs/polish)
[Find design issues/impeccable critique](https://impeccable.style/docs/critique)
[Check implementation/impeccable audit](https://impeccable.style/docs/audit)
[Iterate in the browser/impeccable live](https://impeccable.style/docs/live)
[Build a new surface/impeccable <describe it>](https://impeccable.style/docs/new-work)

[Design ContextPRODUCT.md + DESIGN.md](https://impeccable.style/docs/context)
[New workDirection for new surfaces](https://impeccable.style/docs/new-work)
[Detector CLInpx impeccable detect](https://impeccable.style/docs/detector)
[Design hooks/impeccable hooks](https://impeccable.style/docs/hooks)
[Doctor/impeccable doctor](https://impeccable.style/docs/doctor)
[Config and ignores.impeccable/config.json](https://impeccable.style/docs/config)

Iterate in the browser
----------------------

Pick UI, generate variants, accept one into source.

[Live Mode docs](https://impeccable.style/docs/live)

localhost:4321

Hero headline

Variant 2 of 3

Prev2 / 3NextAccept

1.  [Plan/impeccable shapeThink before you build. Produce a design brief through discovery, not guesswork.](https://impeccable.style/docs/shape)
    
2.  [Review/impeccable critiqueA design review with scoring, persona tests, and automated detection.](https://impeccable.style/docs/critique)
    
3.  [Refine/impeccable polishThe meticulous final pass between good and great.](https://impeccable.style/docs/polish)
    
4.  [Iterate/impeccable liveIterate on UI in the browser. Pick an element, drop a comment, get three variants. Accept one and it writes to source.](https://impeccable.style/docs/live)
    

Already shipped? Use [/impeccable polish](https://impeccable.style/docs/polish)
 on the page that needs work, or [/impeccable audit](https://impeccable.style/docs/audit)
 for checks.

[bolder](https://impeccable.style/docs/bolder)
↔[quieter](https://impeccable.style/docs/quieter)

Two halves of voice. Loud or restrained, never neutral.

[audit](https://impeccable.style/docs/audit)
→[harden](https://impeccable.style/docs/harden)

Find the technical issues. Then fix them.

[critique](https://impeccable.style/docs/critique)
→[polish](https://impeccable.style/docs/polish)

Review the work. Then refine it.

[init](https://impeccable.style/docs/init)
→[shape](https://impeccable.style/docs/shape)

Capture the product. Then plan the surface.

Create 2

*   [impeccableGet a next-step recommendation, or describe design work in plain English.](https://impeccable.style/docs/impeccable)
    
*   [shapeThink before you build. Produce a design brief through discovery, not guesswork.](https://impeccable.style/docs/shape)
    

Evaluate 2

*   [auditFive-dimension technical quality check with P0 to P3 severity.](https://impeccable.style/docs/audit)
    
*   [critiqueA design review with scoring, persona tests, and automated detection.](https://impeccable.style/docs/critique)
    

Refine 8

*   [animatePurposeful motion that conveys state, not decoration.](https://impeccable.style/docs/animate)
    
*   [bolderPush safe designs toward impact without sliding into chaos.](https://impeccable.style/docs/bolder)
    
*   [colorizeAdd strategic color to monochrome interfaces without going garish.](https://impeccable.style/docs/colorize)
    
*   [delightSmall moments of personality that turn functional into memorable.](https://impeccable.style/docs/delight)
    
*   [layoutFix layout, spacing, and visual rhythm.](https://impeccable.style/docs/layout)
    
*   [overdrivePush an interface past conventional limits. Shaders, physics, 60fps, cinematic transitions.](https://impeccable.style/docs/overdrive)
    
*   [quieterTone down designs that are shouting without losing their intent.](https://impeccable.style/docs/quieter)
    
*   [typesetFix typography that feels generic, inconsistent, or accidental.](https://impeccable.style/docs/typeset)
    

Simplify 3

*   [adaptMake designs work across screens, devices, and contexts without amputating features.](https://impeccable.style/docs/adapt)
    
*   [clarifyRewrite confusing UX copy so interfaces explain themselves.](https://impeccable.style/docs/clarify)
    
*   [distillRuthless subtraction. Strip designs to their essence.](https://impeccable.style/docs/distill)
    

Harden 4

*   [hardenMake interfaces production-ready. Edge cases, i18n, error states, overflow.](https://impeccable.style/docs/harden)
    
*   [onboardDesign first-run experiences, empty states, and paths to value.](https://impeccable.style/docs/onboard)
    
*   [optimizeDiagnose and fix UI performance from LCP to bundle size.](https://impeccable.style/docs/optimize)
    
*   [polishThe meticulous final pass between good and great.](https://impeccable.style/docs/polish)
    

System 3

*   [documentGenerate a spec-compliant DESIGN.md that captures your visual system so every AI agent stays on-brand.](https://impeccable.style/docs/document)
    
*   [extractPull reusable components, tokens, and patterns into the design system.](https://impeccable.style/docs/extract)
    
*   [liveIterate on UI in the browser. Pick an element, drop a comment, get three variants. Accept one and it writes to source.](https://impeccable.style/docs/live)

---

# impeccable | Impeccable

[Skip to content](https://impeccable.style/docs/impeccable#main)

When to use it
--------------

`/impeccable` is the main command. Use it in two ways:

*   Run `/impeccable` by itself when you want the skill to inspect the project and recommend what to do next.
*   Add a plain-English request when you know the outcome but not the exact command.

Reach for `/impeccable` directly when:

*   **You are not sure where to start.** It checks whether setup files exist, looks at the current project state, and recommends two or three next commands. It asks before running anything.
*   **You are not sure which command fits.** Describe what you want in plain English and let the skill pick the right approach.
*   **The work spans multiple disciplines.** “Redo this hero section” touches layout, type, color, and motion. One command cannot own that.
*   **You want freeform design help.** Use the main command when no specialist command maps cleanly to the work.

If this is a new project, start with `/impeccable init`. That creates the setup files every other command reads.

How it works
------------

Most AI-generated UIs fail the same way: generic fonts, purple gradients, card grids on card grids, glassmorphism everywhere. `/impeccable` gives the model stronger design instructions before it writes code.

Two files at your project root shape everything the skill does:

*   **`PRODUCT.md`** says what the project is for: platform, audience, product purpose, positioning, real evidence, and brand commitments.
*   **`DESIGN.md`** says how the interface should look: colors, typography, components, elevation, and design rules.

Every command reads both files before generating, plus any brief for the specific surface you named. The judgment that changes the most is the surface’s **mode**, which names what the visitor came to do: Persuade, Operate, Read, or Experience. Impeccable reads that from the surface itself rather than from what the company sells, so one project can hold all four. See [Design Context](https://impeccable.style/docs/context)
 for what each mode changes.

On first use in a project, `/impeccable` may route you into `init`: a short interview that writes `PRODUCT.md` and offers to write `DESIGN.md`. Future commands read those files without asking again.

Try it
------

Run it with no command to get your bearings:

    /impeccable

It sizes up the project and points you at the best next move. For example: no `DESIGN.md` yet, run `document`; unresolved findings in files you are editing, run `polish`. It waits for you to choose.

Or describe what you want and it does the work directly:

    /impeccable redo this hero section

    /impeccable build me a pricing page for a developer tool

Both prompts are vague on purpose. `/impeccable` will choose the right command or run the work directly, using your setup files when they exist.

For visual iteration in the browser rather than chat:

    /impeccable live

Pick any element on your running dev server. Drop a comment or stroke. Get three production-quality variants hot-swapped in via HMR. Accept the one you want and it writes back to source.

Pin commands back as shortcuts
------------------------------

v3.0 consolidated 18 standalone skills into a single `/impeccable` with 23 commands. If you miss the short form of a command, pin it back:

    /impeccable pin critique

From now on, `/critique` invokes `/impeccable critique` directly. It writes a lightweight redirect skill that delegates to the parent, so updates to the skill flow through without re-pinning.

Useful pins to try:

*   `/impeccable pin polish` for final-pass work
*   `/impeccable pin audit` for deterministic a11y/perf checks
*   `/impeccable pin live` for the browser iteration flow
*   `/impeccable pin critique` for design review

To remove: `/impeccable unpin critique`. Pins live as directories named after the command in your harness skills folder (`.claude/skills/critique/`, `.cursor/skills/critique/`, etc.), so you can also delete them manually.

Pitfalls
--------

*   **Treating it like a style guide.** It is an opinionated design partner, not a linter. The defaults exist to raise the floor, not to overrule your judgment. If you have a real reason to push back (brand guideline, accessibility constraint, user research), push back and explain why. The skill will work with you. What produces worse output is ignoring the opinion without a reason.
*   **Expecting it to fix existing code.** `/impeccable` is for creation. For refinement, reach for `/impeccable polish`, `/impeccable distill`, or `/impeccable critique` instead.
*   **Running it before `init` has saved context.** On a fresh project it will interview you mid-flight, which is fine but slower. Running `/impeccable init` first is smoother.
*   **Letting it judge the wrong mode.** A landing page and a settings screen need different defaults, and the mode comes from the surface you named. If a request spans both, scope it to one surface at a time or say which mode you mean.

---

# extract | Impeccable

[Skip to content](https://impeccable.style/docs/extract#main)

01 Discover drift Repeated hex values, button variants, spacing scales, text styles.

02 Propose primitives Token names, component APIs with variant + size, text styles.

03 Migrate call sites Replace duplicated CSS with the new primitives. No orphan code left behind.

The skill only extracts what's used three or more times with the same intent. Two usages are not a pattern, and migration always happens in the same pass.

When to use it
--------------

`/impeccable extract` is for the moment your codebase has accidentally become a design system. Repeated button styles in 12 places. Three variants of the same card. Hex colors scattered throughout. Hand-rolled spacing that accidentally matches a scale. Reach for it when you want to consolidate this drift into reusable primitives.

Use it after a product has shipped enough features to reveal the patterns. Premature extraction creates abstractions that do not match reality.

How it works
------------

The skill discovers the design system structure first, then identifies extraction opportunities:

1.  **Tokens**: find repeated literal values (colors, spacing, radii, shadows, font sizes). Propose token names, add to the token system, replace usages.
2.  **Components**: find UI patterns that repeat with minor variation (buttons, cards, inputs, modals). Extract into a single component with variants, migrate callers.
3.  **Composition patterns**: find layout or interaction patterns that repeat (form rows, toolbar groups, empty states). Extract into composition primitives.
4.  **Type styles**: find repeated font-size + weight + line-height combinations. Extract into text styles.
5.  **Animation patterns**: find repeated easing, duration, or keyframe combinations. Extract into motion tokens.

The skill is cautious. It only extracts things used three or more times, with the same intent. It never extracts “because it might be reused later”. Premature abstraction is worse than duplication.

Try it
------

    /impeccable extract the button styles

Expected output:

*   Found 14 button instances across 8 files
*   4 distinct variants: primary (filled accent), secondary (bordered), ghost (text-only), destructive (filled red)
*   All 4 variants use the same size scale (small, default, large)
*   Extracted into `<Button variant="primary" size="default">` with token-driven styles
*   Migrated 14 call sites, removed ~180 lines of duplicated CSS
*   Added 3 missing tokens: `--button-radius`, `--button-padding-y`, `--button-padding-x`

Pitfalls
--------

*   **Extracting too early.** Two usages are not a pattern. Three might be. Wait until the pattern is obvious.
*   **Over-generalizing.** The extracted component should match the current use cases closely, not anticipate every possible future one. You can always add variants later.
*   **Forgetting the migration.** Extraction without migration leaves the old duplicated code around and creates a third way of doing the same thing. Always migrate in the same pass.
*   **Extracting things that differ in intent.** Two buttons that look similar but serve different purposes (primary action vs link styled as button) should probably stay separate.

---

# shape | Impeccable

[Skip to content](https://impeccable.style/docs/shape#main)

brief.md Output of /impeccable shape

Purpose Let committed subscribers change what they get without losing them to unsubscribe.

User Rushed, on mobile, mid-meeting. Reading fast, low patience.

Content 4 digest types, 2 cadences, one opt-out-all at the bottom.

Feeling Calm, trustworthy, no dark patterns.

Constraints Mobile-first. WCAG AA contrast. One column, no modals.

Hand it to `/impeccable` or any implementation flow.

A shape brief is a compass, not a spec. It captures intent, not UI. Implementation skills read it before writing a line of code.

When to use it
--------------

`/impeccable shape` is where a feature starts. Before anyone writes code, before anyone argues about the hero treatment, before anyone picks a font. Use it to force a discovery conversation about purpose, users, content, and constraints, then capture the answers as a design brief the implementation skills can lean on.

Reach for it whenever a feature is about to start, a ticket is vague, or you catch yourself writing JSX to figure out what the product should be.

How it works
------------

Most AI-generated UIs fail not because of bad code, but because of skipped thinking. The model jumps to “here is a card grid” without asking “what is the user trying to accomplish”. `/impeccable shape` inverts that order.

The skill runs a structured discovery interview in conversation. It will not write code during this phase. The questions cover:

*   **Purpose and context**: what the feature is for, who uses it, what state of mind they are in
*   **Content and data**: what is displayed, realistic ranges, edge cases, what is dynamic
*   **Design goals**: the single most important thing, the intended feeling, reference examples
*   **Constraints**: technical, content, accessibility, localization

You answer naturally. The skill asks follow-ups, not a form. At the end it produces a design brief: a structured artifact you can hand to `/impeccable` or any other implementation skill.

Note: if you want the discovery _and_ the build in one go, just describe the surface. A plain `/impeccable a settings screen for team billing` runs the same discovery, resolves the visual direction with you, and continues into implementation. See [New work](https://impeccable.style/docs/new-work)
. `shape` standalone is for when you want only the brief, so you can take it to whatever implementation approach you prefer.

When `shape` has already run its interview, new-work reuses those confirmed answers rather than asking again.

Try it
------

    /impeccable shape a daily digest email preferences page

Expect a 5 to 10 question conversation. The skill asks things like “who is the person opening this, and are they already committed or still curious” and “what happens when the user has unsubscribed from everything, do we hide the feature or show something”. You answer, and a brief materializes.

From there you can hand the brief to `/impeccable`, `/impeccable polish`, or any other skill. Or just use it as a reference while you build by hand.

Pitfalls
--------

*   **Skipping it because it feels slow.** The interview is maybe 5 minutes. The rewrites you avoid are measured in hours.
*   **Treating the brief as a spec.** It is a compass, not a checklist. It captures intent, not UI.
*   **Answering with “standard” or “normal”.** Specificity is the whole point. If a user is “rushed, on mobile, between meetings”, say so. That changes everything downstream.

---

# audit | Impeccable

[Skip to content](https://impeccable.style/docs/audit#main)

Welcome message

click here

Featured Item

← →

CONTRAST

Welcome message

click here

READABILITY

Featured Item

TOUCH TARGET

← →

Hidden issues → Identified problems with recommendations

/impeccable audit the checkout flow

src/checkout/\*\*

2.6 / 4

Accessibility 2 / 4

Performance 3 / 4

Theming 2.5 / 4

Responsive 3 / 4

Anti-patterns 2.8 / 4

P02 P15 P28 P314

Five dimensions scored 0 to 4, each finding tagged P0 (blocks release) to P3 (polish). Audit documents; it doesn't fix. Route the findings into `/impeccable harden`, `/impeccable polish`, or `/impeccable optimize`.

When to use it
--------------

`/impeccable audit` is the technical counterpart to `/impeccable critique`. Where `/impeccable critique` asks “does this feel right”, `/impeccable audit` asks “does this hold up”. It runs accessibility, performance, theming, responsive design, and anti-pattern checks against the implementation, scores each dimension 0 to 4, and produces a plan with P0 to P3 severity ratings.

Use it before shipping, during a quality sprint, or whenever a tech lead says “we should really look at accessibility”.

How it works
------------

The skill scans your code across five dimensions:

1.  **Accessibility**: WCAG contrast, ARIA, keyboard nav, semantic HTML, form labels.
2.  **Performance**: layout thrashing, expensive animations, missing lazy loading, bundle weight.
3.  **Theming**: hard-coded colors, dark mode coverage, token consistency.
4.  **Responsive**: breakpoint behavior, touch targets, mobile viewport handling.
5.  **Anti-patterns**: the same deterministic checks the [Detector CLI](https://impeccable.style/docs/detector)
     runs.

Each dimension gets a 0 to 4 score. Each finding gets a severity: P0 blocks the release, P1 should fix this sprint, P2 is next cycle, P3 is polish. You get back a single document you can paste into a ticket tracker.

Audit does not fix anything. It documents. Route the findings to `/impeccable polish`, `/impeccable harden`, or `/impeccable optimize` depending on the category.

**On a native project, audit runs a different pass.** When `PRODUCT.md` declares `ios`, `android`, or `adaptive`, the five web dimensions do not apply, so audit swaps to a native version: VoiceOver and TalkBack behavior, Dynamic Type and font scaling, touch targets at platform minimums, and conformance to the Apple HIG or Material 3 conventions your platform is held to. The deterministic detector has no native equivalent and sits out. See [Design Context](https://impeccable.style/docs/context)
 for how the platform is set, which is usually automatically.

Try it
------

    /impeccable audit the checkout flow

Expected output:

    Accessibility: 2/4 (partial)
      P0: Missing form labels on 4 inputs
      P1: Contrast 3.1:1 on disabled button state
      P2: No visible focus indicator on custom dropdown
    
    Performance: 3/4 (good)
      P1: Hero image not lazy-loaded (340KB)
      ...

Hand the P0s to `/impeccable harden`, the theming and typography P1s to `/impeccable typeset` and `/impeccable polish`, the rest to `/impeccable polish`.

Pitfalls
--------

*   **Confusing it with `/impeccable critique`.** Audit is implementation quality. Critique is design quality. Run both for a full picture.
*   **Fixing P3s before P0s.** The severity scale exists for a reason. Start at the top.
*   **Skipping the dimensions you think are fine.** Theming and responsive are the ones most people assume are fine until they are not.

---

# critique | Impeccable

[Skip to content](https://impeccable.style/docs/critique#main)

Dashboard

Welcome to your dashboard where you can manage things

Create Import Export Settings

Recent Activity

No items to display at this time

Dashboard

HIERARCHY

Welcome to your dashboard where you can manage things

REDUNDANT

NO PRIMARY

Create Import Export Settings

DEAD END

Recent Activity

No items to display at this time

Confusing design → UX issues identified with fixes

AI slop verdict FAIL

gradient-text · ai-color-palette · nested-cards

Heuristics (Nielsen)

Visibility of status 3

Match with real world 2

Consistency & standards 2

Error prevention 3

Recognition over recall 1

Personas

The evaluator Comparing us to two alternatives on a Tuesday evening.

2 / 4

The returning user Knows the product, on mobile, in a hurry.

3 / 4

The skeptic Has seen every SaaS landing and is bored.

1 / 4

The two passes (LLM design review plus the deterministic detector) merge into one prioritized list. What's working, what to fix, and the provocative questions worth answering before shipping.

When to use it
--------------

Reach for `/impeccable critique` when you want an honest second opinion on something you already built. Not “does it work” but “is it any good”. The skill scores your interface against Nielsen’s 10 heuristics, runs cognitive load checks, tests through persona lenses, and cross-references an automated detector for 25 concrete anti-patterns.

Use it when a page is functionally done and you want to know if it reads as intentional or as AI slop.

How it works
------------

`/impeccable critique` runs two independent assessments in parallel so they do not bias each other.

The first is an **LLM design review**: the model reads your source, visually inspects the live page if browser automation is available, and walks the impeccable skill’s full DO/DON’T catalog. It scores Nielsen’s heuristics, counts cognitive load failures, traces the emotional journey through the flow, and flags AI slop.

The second is an **automated detector** (`npx impeccable detect`) that deterministically finds gradient text, purple palettes, side-tab borders, nested cards, line length problems, and the other visible fingerprints of generic AI output.

The two reports merge into one prioritized list: what is working, the three to five things that need fixing, and the provocative questions worth answering before shipping.

Try it
------

Point it at a page:

    /impeccable critique the homepage hero

You get back a scored report. Typical shape:

*   **AI slop verdict**: pass / fail with the specific tells
*   **Heuristic scores**: 10 numbers, 0 to 4
*   **Cognitive load**: failure count out of 8
*   **Priority issues**: three to five items, each with what, why, and fix
*   **Questions to answer**: the ones the interface itself cannot decide for you

From there, pair with `/impeccable polish` or `/impeccable distill` to act on the fixes.

Pitfalls
--------

*   **Running it on incomplete work.** Critique is for finished pages. An empty state with three TODOs will score badly because it is not done, not because it is bad.
*   **Ignoring the questions at the end.** They are usually the fixes that change the design most.
*   **Treating the heuristic scores as a grade.** They are diagnostic, not evaluative. A 3/4 on a heuristic that matters less for your context is fine.

---

# polish | Impeccable

[Skip to content](https://impeccable.style/docs/polish#main)

User Profile

John Doe

Developer

Edit Profile

User Profile

JD

John Doe

Developer

Edit Profile

Rough edges → Refined, pixel-perfect details

When to use it
--------------

`/impeccable polish` is the last thing you run before shipping. It hunts down the small details that separate a shipped feature from a polished one: half-pixel misalignments, inconsistent spacing, forgotten focus states, loading transitions that flash, copy that drifts in tone. It also aligns the feature with your design system, replacing hard-coded values with tokens, swapping custom components for shared ones, and fixing any drift from established patterns.

Reach for it when the feature is functionally complete, nothing is broken, and something still feels off. Also reach for it when a feature has drifted from the design system and needs to be pulled back in line.

How it works
------------

Polish starts by discovering the design system (tokens, spacing scale, shared components), then works methodically across six dimensions:

1.  **Visual alignment and spacing**: pixel-perfect grid adherence, consistent spacing scale, optical alignment on icons.
2.  **Typography**: hierarchy consistency, line length, widows and orphans, kerning on headlines.
3.  **Color and contrast**: token usage, theme parity, WCAG ratios, focus indicators.
4.  **Interaction states**: hover, focus, active, disabled, loading, error, success. Every state accounted for.
5.  **Transitions and motion**: smooth easing, no layout jank, respect for `prefers-reduced-motion`.
6.  **Copy**: consistent voice, correct tense, no placeholder strings, no stray TODOs.

The skill is explicit about one thing: polish is the last step, not the first. If the feature is not functionally complete, polishing it is wasted work.

Try it
------

    /impeccable polish the pricing page

A healthy run looks like:

    Visual alignment: fixed 3 off-grid elements (8px baseline)
    Typography: tightened h1 kerning, fixed widow on testimonial
    Interaction: added hover state on FAQ items, focus ring on email input
    Motion: softened modal entrance, added reduced-motion fallback
    Copy: removed one "Lorem ipsum" stray, aligned button voice

Five small fixes, no rewrites. That is the shape of a good polish pass.

Pitfalls
--------

*   **Polishing work that is not done.** If there are TODOs in the code, you are not ready. Run `/impeccable polish` on finished features only.
*   **Treating polish as redesign.** Polish refines what exists. If you find yourself rearchitecting a layout, you needed `/impeccable critique` or `/impeccable layout` instead.
*   **Running `/impeccable polish` without `/impeccable audit` first.** Polish catches feel-based issues. Audit catches measurable ones. Use both.

---

# quieter | Impeccable

[Skip to content](https://impeccable.style/docs/quieter#main)

🎉✨🚀

AMAZING DEAL!

Don't miss out on this INCREDIBLE opportunity!!!

BUY NOW!! LEARN MORE

Limited Time Offer

Save 20% on annual plans. Offer ends Friday.

View Plans Maybe Later

Overwhelming design → Calm, focused interface

When to use it
--------------

`/impeccable quieter` is the counterweight to `/impeccable bolder`. Reach for it when an interface is visually aggressive, overstimulating, or trying to do too many things at full volume. Neon on dark, gradient text everywhere, 6 accent colors, everything animated, 20px shadows. Use quieter when the design needs to breathe and you want refinement without losing the point of view.

Also useful after `/impeccable bolder` goes a little too far.

How it works
------------

The skill works by reduction across four axes:

1.  **Color**: desaturate, lower chroma in OKLCH, pull accents back to a single primary plus muted support. No more than two intentional colors.
2.  **Contrast**: soften extreme darks and lights, pull the range in. Backgrounds move from pure white and pure black to paper and ink.
3.  **Decoration**: remove shadows that are not doing work, drop borders that are not carrying structure, retire gradients that exist for energy rather than hierarchy.
4.  **Motion and effect**: slow animations down, remove anything that auto-plays, drop parallax and blur unless they serve readability.

The skill preserves the design’s intent. If the original had a point of view, the quieter version has the same point of view with more confidence. Refinement, not neutralization.

Try it
------

    /impeccable quieter the pricing page

Typical diff:

*   Gradient text on the price removed, replaced with solid ink at one weight heavier
*   Three accent colors reduced to one (magenta), the other two become neutral variants
*   Card shadows reduced from `0 20px 40px rgba(0,0,0,0.2)` to `0 1px 0 var(--color-mist)` (a hairline)
*   Background switches from dark gradient to paper with a subtle cream wash at the top
*   Hero animation from 1.2s easeOut with 3 staggered elements to a single 260ms fade-in

Pitfalls
--------

*   **Over-applying.** Quieter can strip personality if you run it on something that was already measured. Use it when the design is too loud, not when it is correctly assertive.
*   **Confusing quieter with distill.** Quieter reduces intensity. Distill removes elements. They are different moves.
*   **Running it in response to a critique that says “too busy”.** Busy usually means too many things, not too loud. Try `/impeccable distill` first.

---

# bolder | Impeccable

[Skip to content](https://impeccable.style/docs/bolder#main)

Introducing Our Product

A solution for modern teams

Learn More

Introducing Our Product

A solution for modern teams

Learn More

Timid design → Bold, confident design

When to use it
--------------

Reach for `/impeccable bolder` when the interface looks like every other interface. Generic sans, medium weights, soft shadows, modest accent color, reasonable spacing, forgettable. The design is not wrong, it is just safe. Use bolder when a project can handle presence and the current state is not bringing any.

Do not use it on dashboards people stare at for hours. Boldness earns its place on marketing pages, hero moments, and content features. Not in operator tools.

How it works
------------

The skill amplifies four axes without breaking usability:

1.  **Scale**: display type gets pushed to clamp(3rem, 6vw, 6rem) or beyond. Headlines that fill the viewport, not hedge it.
2.  **Weight contrast**: light 300 against heavy 800 instead of medium against regular. Real tension, not a shrug.
3.  **Color commitment**: the accent color shows up at full strength, not diluted. Backgrounds can take a stance (ink, accent, cream) instead of all-paper.
4.  **Compositional confidence**: asymmetry, off-grid, pullquotes, hanging punctuation, scale jumps. The layout has a voice.

The skill does not add more. It amplifies what is already there. If the design has three colors, bolder does not add a fourth, it commits harder to the three.

Try it
------

    /impeccable bolder the landing page hero

Expected changes:

*   Hero heading from 3rem to clamp(3.5rem, 7vw, 6.5rem), display font, weight 700
*   Subhead from regular to italic at 1.5rem, pulled 8px left of the heading for optical alignment
*   Background switches from paper to a cream-to-paper gradient, creating a warmer container
*   CTA button fills, drops shadow removed, border radius reduced, hover state inverts colors
*   Supporting image pushed slightly off-grid with a negative top margin, creating asymmetry

Pitfalls
--------

*   **Running it on the wrong page.** Product dashboards, settings, and forms should not be bold. They should be legible. Use `/impeccable layout` or `/impeccable polish` instead.
*   **Confusing bold with loud.** Bold means committed and confident. Loud means shouting. Bolder is the former. If the result feels aggressive, follow up with `/impeccable quieter`.
*   **Pairing it with `/impeccable delight` in the same pass.** Delight works best against a stable visual baseline. Bold first, stabilize, then delight.

---

# distill | Impeccable

[Skip to content](https://impeccable.style/docs/distill#main)

Dashboard

⚙️ 🔔 ❓ ⋮

Revenue  
**$12,345**

Users  
**1,234**

Growth  
**+12%**

Bounce  
**32%**

📊 View detailed analytics →

🎯 Set up goals →

This Month

$12,345

↑ 12% from last month

1,234

Active users

68%

Retention

Cluttered interface → Essential elements only

When to use it
--------------

`/impeccable distill` removes what should not be there. Competing buttons, redundant information, decorative borders, three fonts where one works, six navigation items where three belong. Use it when an interface feels cluttered, busy, or like it is trying to do too much at once.

Reach for it after `/impeccable critique` flags “cognitive load” or “visual noise”, or any time a page has grown by accretion and no one has done the editing.

How it works
------------

The skill starts from one question: what is the single job this interface is trying to do? Everything that does not help that job is on the chopping block.

It works in two passes:

1.  **Assess the complexity sources**. Too many elements, excessive variation, information overload, visual noise, confusing hierarchy, feature creep. Name each one.
2.  **Edit ruthlessly**. Remove what is not essential. Combine what can be combined. Hide what can wait. Consolidate variation into a single treatment. Commit to a single visual language.

The principle: every element on the page has to justify its existence. Fewer obstacles, not fewer features.

Try it
------

    /impeccable distill this dashboard

Before: four card styles, three button variants, two header treatments, a sidebar with 14 items grouped into 5 sections.

After a `/distill` pass, typical changes:

*   Collapse the four card styles into one
*   Pick one button variant, demote the others to text links
*   Unify the headers
*   Group the sidebar into 3 sections, not 5
*   Hide advanced options behind a disclosure

Fewer things. Each one clearer.

Pitfalls
--------

*   **Confusing distill with delete.** Distill removes obstacles. It does not remove features users need. If a user relies on something daily, find a way to keep it quietly, not a way to cut it.
*   **Running it too early.** If the feature is still growing, distilling it now means distilling the same thing again next week. Wait until the shape is stable.
*   **Expecting it to replace hierarchy work.** Sometimes the right fix is not removing things, it is arranging them. Reach for `/impeccable layout` when the problem is layout, not quantity.

---

# harden | Impeccable

[Skip to content](https://impeccable.style/docs/harden#main)

⚠️

Error

Something went wrong

OK

Form Input

!

Connection failed

Unable to reach the server. Check your internet connection and try again.

Retry Connection

Email Address

Please enter a complete email address

Fragile UI → Robust error handling

When to use it
--------------

`/impeccable harden` is for the day your interface meets reality. Real user data is messy: names that are 60 characters long, product titles in German, prices in the billions, 500 errors, offline modes, right-to-left text. Designs that only work with perfect data are not production-ready.

Reach for it before launch, before opening to a new market, or any time a bug report starts with “our user had a really long name and”. For first-run flows, empty-state activation, and onboarding design, reach for `/impeccable onboard` instead.

How it works
------------

The skill works through four dimensions of real-world resilience:

1.  **Text and data extremes**. Long text, short text, special characters, emoji, RTL, numbers in the billions, 1000-item lists.
2.  **Error scenarios**. Network failures, API 4xx/5xx, validation errors, permission errors, rate limits, concurrent operations.
3.  **Internationalization**. Long translations (German is often 30% longer than English), RTL languages, date and number formats, currency symbols, character sets.
4.  **Device and context**. Touch targets, offline behavior, slow connections, low-power mode.

For each dimension it identifies the failure mode, then applies the concrete fix: overflow handling, informative error UI, i18n-safe layouts, pluralization, sensible fallbacks.

Try it
------

Start with one page and one dimension:

    /impeccable harden the user profile page for long names

Expected output:

*   `.user-name` now has `text-overflow: ellipsis` with a tooltip for the full value
*   `.bio` switched from fixed height to `max-height` with a “show more” disclosure
*   Added an empty state for users with no bio
*   Added a skeleton loader for the async avatar fetch
*   Tested at name lengths 1, 20, 60, 200 characters

Run it per-page, not all at once. The first run is the biggest; subsequent runs find fewer issues as patterns solidify.

Pitfalls
--------

*   **Waiting for a bug report.** Harden is preventative. If you find yourself fixing the same class of bug twice, run `/impeccable harden` across the feature.
*   **Treating error and empty states as an afterthought.** Most hardening work is error and empty state UI. Budget time for it, not just a `catch` block.
*   **Skipping i18n because “we are English-only for now”.** i18n-safe layouts are still better layouts. Flexible containers, proper text wrapping, generous line-height. None of that hurts English.

---

# colorize | Impeccable

[Skip to content](https://impeccable.style/docs/colorize#main)

TASK OVERVIEW

Design review

Update copy

Final QA

Progress: 1 of 3

TASK OVERVIEW

✓

Design review

Update copy

Final QA

1/3

Monochrome UI → Strategic, harmonious color

When to use it
--------------

`/impeccable colorize` is the counterweight to “everything is gray”. Dashboards that read as a beige wall, forms with no accent, content pages that could be any SaaS product. Reach for it when the interface is functional but emotionally flat, and you want warmth without tipping into the AI color palette (purple-to-pink, cyan neon, dark mode glow).

How it works
------------

The skill starts by reading your brand color if one exists, then decides where color earns its place:

1.  **Primary action** gets the strongest expression of the brand hue.
2.  **Secondary accents** get muted or tinted variants, not a second full color.
3.  **Neutrals** get tinted toward the brand hue at low chroma (around 0.005 to 0.01), which is nearly invisible per pixel but creates subconscious cohesion.
4.  **Content categories** get a limited, intentional accent system, not a rainbow.

Importantly, it uses OKLCH rather than HSL so that equal lightness steps look equal. As lightness moves toward the extremes, chroma drops automatically. This is how you get color that feels considered instead of computed.

Try it
------

    /impeccable colorize the dashboard

Expected diff:

*   Brand color moved from a hardcoded hex to `--color-accent: oklch(62% 0.18 240)`
*   Neutrals tinted with 0.007 chroma toward the brand hue
*   Primary button gets the full accent, secondary buttons get ink/mist
*   Chart series uses 3 distinct hues, all at matched lightness so no series visually dominates
*   Empty state illustration picks up a soft accent wash

Pitfalls
--------

*   **Running it without a brand hue.** Colorize needs a starting point. If `PRODUCT.md` does not specify one, it will ask. Do not let it pick from the AI color palette defaults.
*   **Expecting it to fix the AI color palette problem.** If your design already has purple gradients and cyan neon, you need `/impeccable quieter` first, then colorize can rebuild.
*   **Using it on already-colorful interfaces.** That is a `/impeccable quieter` job. Colorize adds, it does not subtract.

---

# typeset | Impeccable

[Skip to content](https://impeccable.style/docs/typeset#main)

Project Update

Q1 Design Sprint

The team completed the redesign of the dashboard. All components have been reviewed and approved by stakeholders.

Updated 2 hours ago

Project Update

Q1 Design Sprint

The team completed the redesign of the dashboard. All components reviewed and approved.

Updated 2 hours ago

No type hierarchy → Clear, intentional typography

When to use it
--------------

Reach for `/impeccable typeset` when the text on a page looks like default typography instead of designed typography. Muddy hierarchy, three sizes that look the same, body copy at 14px, a display font that is actually just Inter bold, headlines with no kerning attention.

Common triggers: “hierarchy feels flat”, “readability is off”, “fonts look generic”.

How it works
------------

The skill assesses typography across five dimensions:

1.  **Font choices**: are you using invisible defaults (Inter, Roboto, Arial, Open Sans), does the typeface match the brand, are there more than 2 to 3 families.
2.  **Hierarchy**: are heading, body, and caption clearly different at a glance, is the size contrast at least 1.25x between steps, are weight contrasts legible.
3.  **Sizing and scale**: is there a coherent type scale, does body text meet 16px minimum, is the scale fixed-rem for app UIs or fluid-clamp for marketing pages.
4.  **Readability**: line length 45 to 75 characters, line-height tuned for font and context, contrast.
5.  **Consistency**: same element uses same treatment everywhere, no one-off font-size overrides.

It then fixes what it finds: picks distinctive typefaces, builds a modular scale, widens hierarchy contrast, sets proper line length and leading.

Try it
------

    /impeccable typeset the article layout

Expected diff:

*   Display font swapped from Inter 700 to a real display face
*   Type scale rebuilt: 3rem / 2rem / 1.25rem / 1rem / 0.875rem, ratio 1.333
*   Body text bumped from 14px to 16px
*   Line length clamped to 68ch on the article column
*   Line-height 1.6 for body, 1.1 for display
*   Removed four one-off `font-size` values scattered in component styles

Pitfalls
--------

*   **Asking for a new font without context.** Typeset will pick based on the `PRODUCT.md` brand voice. If you have not run `/impeccable init`, the suggestion will be generic.
*   **Reaching for typeset when the issue is layout.** If paragraphs are fine but the page feels cramped, you want `/impeccable layout`.
*   **Expecting fluid clamp scales on app UIs.** Typeset uses fixed rem scales for app interfaces. Fluid typography is for marketing and content pages where line length varies dramatically.

---

# onboard | Impeccable

[Skip to content](https://impeccable.style/docs/onboard#main)

When to use it
--------------

`/impeccable onboard` is for the moments that decide whether a new user sticks around: the first screen, the empty state, the setup flow, the product tour, the “what do I do now” gap. Reach for it when activation is weak, when new users drop off before reaching value, or when your product has empty states that say “no items yet” and stop there.

How it works
------------

The command starts from one question: what is the aha moment, and how fast can a new user get there. Every design decision points at that moment.

It works across the surfaces that shape first impressions:

1.  **First-run experience**: the moments immediately after sign-up. Should the user see a tour, a blank canvas, a filled example, or nothing at all. Pick the approach that matches the product.
2.  **Empty states**: every zero-data screen gets oriented. Where am I, why is this empty, what do I do next, what will it look like once it is full.
3.  **Setup and installation**: required configuration is minimized, defaults are smart, each step explains why it matters.
4.  **Progressive disclosure**: advanced features stay out of the way until they are earned.
5.  **Activation events**: the moment a user first experiences the core value is instrumented and celebrated, quietly.

The command resists two common failure modes: over-tutorialized onboarding where users click through a carousel before they can touch anything, and zero-onboarding where users are dropped into an empty app and expected to figure it out.

Try it
------

    /impeccable onboard the editor

Typical output:

*   First-run: replaces empty editor with a filled example document the user can modify. Cancel button discards the example, edit replaces the content with the user’s work.
*   Empty state on document list: “No documents yet. Create your first, or import from Notion, Google Docs, or Markdown.”
*   Setup: reduced from 6 required fields to 1 (workspace name). Everything else has a smart default and can be edited later in settings.
*   Activation: the first time a user saves a document, a quiet toast says “Saved. Your work is in the cloud now.” One-time, not repeated.

Pitfalls
--------

*   **Adding a product tour as the default answer.** Most products do not need a tour. They need a better first screen. Tours are a crutch.
*   **Designing onboarding without defining the aha moment.** If you cannot say in one sentence what the user should feel in the first 60 seconds, go back to `/impeccable shape` first.
*   **Running onboard on a broken flow.** Fix the flow first. Onboarding cannot rescue a product where the core action is broken.

---

# layout | Impeccable

[Skip to content](https://impeccable.style/docs/layout#main)

Team Members

Alice Chen

Designer

Bob Park

Engineer

Team Members

AC

Alice Chen

Designer

BP

Bob Park

Engineer

Equal spacing everywhere → Intentional rhythm and hierarchy

When to use it
--------------

`/impeccable layout` is for pages where nothing is technically wrong but nothing is breathing either. Equal padding everywhere, monotonous card grids, content that runs edge to edge, hierarchy that relies on size alone. Reach for it when a layout “feels off” and you cannot articulate why.

Good triggers: “everything feels crowded”, “it reads like a wall”, “I do not know where to look first”.

How it works
------------

The skill runs through five layout dimensions:

1.  **Spacing**: is the spacing scale consistent or are there random 13px gaps, are related elements grouped tightly with generous space between groups, is there any rhythm at all.
2.  **Visual hierarchy**: does the eye land on the primary action within 2 seconds, is the hierarchy doing real work or is everything shouting.
3.  **Grid and structure**: is there an underlying grid or is the layout random, are elements aligned to baselines.
4.  **Rhythm**: does the page alternate between tight and generous spacing, or is everything uniform.
5.  **Density**: is the layout cramped or is it wasteful, does density match the content type.

Fixes usually involve rebuilding the spacing scale, introducing asymmetry, collapsing monotonous grids into a mixed layout with hero and supporting elements, and giving the primary action real space.

Try it
------

    /impeccable layout the settings page

Typical changes:

*   Spacing scale unified to 8 / 16 / 24 / 48 / 96px
*   Section breaks at 48px, row gaps at 16px, form field groups at 8px
*   Primary actions pulled out of the form flow with 32px buffer
*   Decorative borders removed, replaced with spacing-driven grouping
*   Sidebar and main column proportions rebalanced (280 / flex vs 25 / 75)

Pitfalls
--------

*   **Confusing arrange with distill.** If the problem is too many things, run `/impeccable distill` first. Layout is for arranging what is already the right set.
*   **Expecting it to rescue a broken grid.** If the page has no grid at all, arrange will build one. Just know that the diff is going to be larger than you expect.
*   **Ignoring the hierarchy verdict.** If arrange says “nothing is primary”, no amount of spacing work fixes that. You need a content decision, not a layout tweak.

---

# overdrive | Impeccable

[Skip to content](https://impeccable.style/docs/overdrive#main)

It's time to spark your imagination. Welcome to the Impeccable Community.

Paul Bakaus

It's time to spark your imagination.  
Welcome to the Impeccable Community.

Static flat card → Laser-etched signature effect

When to use it
--------------

`/impeccable overdrive` is for the moments where you want to impress. A hero that uses WebGL. A table that handles a million rows. A dialog that morphs out of its trigger element. A form that validates in real-time with streaming feedback. A page transition that feels cinematic. Use it when the project budget allows for technical ambition and the outcome needs to feel extraordinary.

Do not use it on operator tools, dashboards, or anything where reliability beats spectacle. Overdrive burns complexity for effect, and that trade-off is only worth it on moments that matter.

How it works
------------

The skill picks one moment to make extraordinary and commits to it, rather than spreading effort across the whole interface. It then reaches for techniques most AI-generated UIs never touch: WebGL shaders, spring physics, Scroll Timeline, View Transitions, canvas animation, GPU-accelerated filters. Everything is budgeted, profiled, and tested at 60fps, with reduced-motion fallbacks baked in.

Overdrive output is announced with `──── ⚡ OVERDRIVE ────` so you know you are entering a more ambitious mode. Expect larger diffs, new dependencies, and implementation depth beyond what other skills produce.

Try it
------

    /impeccable overdrive the landing hero

One concrete run might replace a static hero with a WebGL shader background driven by mouse position, a display headline that reveals with a mask on scroll using the Scroll Timeline API, and a View Transition on the CTA that morphs into the next page. Plus a reduced-motion fallback that swaps all of it for a clean static composition.

Pitfalls
--------

*   **Using it everywhere.** Overdrive works because it is rare. If every page has cinematic moments, none of them are cinematic.
*   **Shipping without reduced-motion fallbacks.** Non-negotiable. Overdrive adds them automatically; do not remove them.
*   **Ignoring performance.** Extraordinary moments still need to hit 60fps. If the effect drops frames, cut it or optimize. Slow spectacle is worse than simple done well.
*   **Running overdrive before the base interface is solid.** Spectacle on a broken foundation reads as distraction, not delight.

---

# adapt | Impeccable

[Skip to content](https://impeccable.style/docs/adapt#main)

Text too small...

Mobile

Broken ✗

Desktop

Works ✓

Mobile

Stacked ✓

Tablet

2-col ✓

Desktop

Sidebar ✓

Fixed layout → Responsive across devices

When to use it
--------------

`/impeccable adapt` is for taking a design built for one context and making it work in another. Mobile from desktop, tablet from mobile, print from web, embedded from standalone, email from dashboard. Reach for it when the source design is solid but falls apart at other breakpoints, on touch, or in a different container.

Not for building responsive from scratch. For that, start with `/impeccable` and shape the layout responsive-first. Adapt is for the “we never thought about mobile” backfill.

How it works
------------

The skill works through four dimensions of contextual fit:

1.  **Breakpoints and fluid layout**: collapse multi-column to single, adjust clamp ranges, introduce new breakpoints where the design genuinely breaks.
2.  **Touch targets**: minimum 44px hit areas, sufficient spacing between adjacent targets, larger tap zones than visual bounds where needed.
3.  **Navigation patterns**: desktop sidebars become mobile bottom nav or slide-outs, dense toolbars collapse into menus, hover states get touch equivalents.
4.  **Content priority**: decide what must be visible, what can collapse into disclosures, what can be removed entirely for that context.

The non-negotiable rule: adapt, do not amputate. Critical functionality cannot disappear on mobile just because it is inconvenient. Find a way to fit it, redesign the interaction, or reconsider whether it was really critical on desktop.

**On a native project, adapt works in native dimensions.** When `PRODUCT.md` declares `ios`, `android`, or `adaptive`, breakpoints and CSS clamps are the wrong vocabulary, so adapt swaps to a native version: phone to tablet, one platform’s conventions to the other’s, and web patterns translated into native affordances rather than transplanted. See [Design Context](https://impeccable.style/docs/context)
.

Try it
------

    /impeccable adapt the settings page for mobile

Expected changes:

*   Three-column grid becomes single column with section headers acting as sticky dividers
*   Sidebar nav moves to a horizontal scroller above the content
*   Toggles gain 8px vertical padding so they meet 44px touch targets
*   Inline help text moves to tap-to-reveal, not hover
*   The “Danger zone” section expands fully on mobile instead of collapsing, because it contains irreversible actions and we want users to see them clearly

Pitfalls
--------

*   **Amputating features.** If the mobile version hides things the desktop version can do, that is a regression, not an adaptation. Fight for the feature.
*   **Treating mobile as “smaller desktop”.** Mobile is a different context: thumbs, interruption, short sessions. Adapt to the context, not to the viewport width.
*   **Skipping `/impeccable harden` afterward.** Responsive layouts reveal edge cases. Run hardening after adapt to catch the ones that only show up at 320px.

---

# optimize | Impeccable

[Skip to content](https://impeccable.style/docs/optimize#main)

BUNDLE SIZE

847 KB

RENDER TIME

2.4s

LAYOUT SHIFTS

CLS: 0.18

BUNDLE SIZE

124 KB (-85%)

RENDER TIME

0.3s (-88%)

LAYOUT SHIFTS

CLS: 0.02 (excellent)

Heavy, slow UI → Lightweight, performant

When to use it
--------------

`/impeccable optimize` is for interfaces that feel slow. First paint takes forever, scrolling janks, images pop in late, interactions feel laggy, the bundle ships 800KB of JavaScript. Use it when the Web Vitals are bad or when users are complaining that things are sluggish.

Do not use it as premature optimization. If LCP is 1.1s and INP is 80ms, stop. The design work matters more.

How it works
------------

The skill works through five perf dimensions:

1.  **Loading and Web Vitals**: LCP, INP, CLS. Identify what is blocking the first paint, what is delaying interaction, what is shifting layout.
2.  **Rendering**: unnecessary re-renders, missing memoization, expensive reconciliation, layout thrash in loops.
3.  **Animations**: is anything animating layout properties, are transforms and opacity the only thing touched, does `will-change` help or hurt here.
4.  **Images and assets**: lazy loading, responsive images (`srcset`, `sizes`), modern formats (WebP, AVIF), dimensions set to prevent CLS.
5.  **Bundle size**: unused imports, oversized dependencies, missing code-splitting, dead code.

The skill measures before and after. Every fix gets quantified. If a change does not move a metric, it gets rolled back.

Try it
------

    /impeccable optimize the homepage

Expected shape:

    LCP: 3.2s → 1.4s
      - Hero image preloaded (-800ms)
      - Removed render-blocking font stylesheet (-240ms)
      - Deferred analytics script (-180ms)
    
    INP: 240ms → 90ms
      - Debounced scroll handler
      - Memoized expensive list render
      - Removed synchronous layout read in event loop
    
    CLS: 0.18 → 0.02
      - Set dimensions on hero image and logo
      - Reserved space for async header badge
    
    Bundle: 340KB → 180KB
      - Removed unused lodash import (52KB)
      - Code-split the playground route (78KB)
      - Dropped deprecated icon set (30KB)

Pitfalls
--------

*   **Optimizing before measuring.** Without baseline metrics, you cannot tell what helped. Run `/impeccable optimize` with specific Web Vitals numbers, not vibes.
*   **Chasing tiny wins.** A 20ms improvement in INP that takes a week is rarely worth it. Optimize has diminishing returns; know when to stop.
*   **Forgetting to re-measure after every change.** The build could have made things worse in a way the skill did not predict. Verify.

---

# clarify | Impeccable

[Skip to content](https://impeccable.style/docs/clarify#main)

Processing Status

Your request is being processed. Please wait while we complete the operation. This may take some time depending on various factors.

⚠️ Warning

Proceeding with this action may result in irreversible consequences to your data and settings configuration.

Submit Request

Saving changes...

About 10 seconds remaining

Delete this project?

This will permanently delete 23 files. You can't undo this.

Save and Continue →

Confusing copy → Clear, actionable language

When to use it
--------------

`/impeccable clarify` is for interface text that makes people stop and think. Confusing labels, ambiguous button copy, error messages that blame the user, tooltips that repeat the label, empty states that say nothing useful. Use it when the problem is not the layout or the color, it is the words.

Good triggers: “users do not understand this field”, “the error message is not helpful”, “I cannot write good button copy”, “this tooltip is a waste”.

How it works
------------

The skill rewrites text across the surfaces where most UX copy problems live:

1.  **Labels and field hints**: direct, specific, say what is expected.
2.  **Button copy**: verb-first, describes the outcome, not the action. “Save changes” not “OK”.
3.  **Error messages**: explain what went wrong, whose fault it is, and what to do next. Never blame the user.
4.  **Empty states**: orient the user, explain why the state is empty, offer a next step.
5.  **Tooltips and helper text**: add information the label cannot carry, never restate it.
6.  **Confirmation dialogs**: name the consequences, not the action.

The skill uses the audience and mental state from `PRODUCT.md` to tune voice. Technical audience gets precise language. Consumer audience gets plain speech. Rushed users get short text. Anxious users (payment, delete) get reassurance.

Try it
------

    /impeccable clarify the billing form

Before and after, typical:

*   Label “Billing address” → “Address on your card”
*   Placeholder “Enter your VAT ID” → “VAT ID (optional, for business)”
*   Error “Invalid input” → “This card number is 15 digits. You entered 14.”
*   Button “Submit” → “Charge $29 and subscribe”
*   Empty state “No transactions yet” → “Your first charge will show up here after your first order.”

Pitfalls
--------

*   **Writing cleverer, not clearer.** Clarify is not for voice upgrades. If the copy is already clear, do not reach for this skill. Use `/impeccable delight` instead when you want personality.
*   **Skipping the audience question.** Clarify needs to know who is reading. If `PRODUCT.md` does not specify audience technical level, the rewrites will be generic.
*   **Running clarify on marketing copy.** Clarify is for functional UX text: labels, errors, instructions. Marketing copy needs a different set of moves and a human writer.

---

# live | Impeccable

[Skip to content](https://impeccable.style/docs/live#main)

▸ See it in action, with the animated demo, at [/live-mode](https://impeccable.style/live-mode)
. This page is the reference for what your AI harness reads when the command runs.

▸ **Status: alpha.** Live Mode works end-to-end and is ready to try, but it still needs more testing against real-world repos and framework configs. Expect rough edges on uncommon setups, and please report what breaks.

localhost:3000

No. 04

### Letters, _occasionally_.

A postcard from the editor, about once a month. No tracking pixels, no "just checking in."

Send me one

‹ 2 / 3 › Accept

/ Pick ✕

Live Mode mid-cycle: the picker outlines the element you chose, the context bar shows which variant you're on, and the global bar stays pinned to the bottom. Accept on this one writes Variant 2 back to source.

When to use it
--------------

Reach for `/impeccable live` when you want to iterate on something visually the way you would in a design tool, but keep production code as the output. The canvas-like flow of Figma without the round trip to an implementation step.

Use it for:

*   **Exploring directions on a real element.** A hero section, a newsletter card, a pricing tier. Three genuinely different takes, side by side, on the actual page with the actual context.
*   **Polishing a piece of UI that is almost right.** You know what feels off but cannot quite say it. Pick the element, scribble “more playful” or draw a stroke through the bit that bugs you, hit Go.
*   **A quick A/B between two directions your team is debating.** Generate variants, accept nothing, walk away. The point was the comparison.

It is NOT for new greenfield features or whole-page redesigns; ask `/impeccable` to build or redesign the surface directly.

How it works
------------

One command brings up a picker overlay on top of your running dev server. You pick any element. A small context bar appears next to it. Type a freeform description or pick one of the action chips (`bolder`, `quieter`, `distill`, `polish`, `typeset`, `colorize`, `layout`, `animate`, `delight`, `overdrive`). Optionally drop comment pins or draw strokes directly on the element first, and the skill reads those as intent.

Hit Go. Three **production-quality variants** get generated, each anchored to a genuinely different design archetype (not three riffs on color) and hot-swapped into the page via your framework’s HMR. Cycle through them with arrow keys. Accept one and the variant is written back to source. Discard all three and the original stays.

It supports Vite, Next.js (including monorepos), SvelteKit, Astro, Nuxt, and plain static HTML. If your dev server has a strict Content Security Policy, the first-run setup detects it and offers a one-time, dev-only patch so the picker can load. `DESIGN.md` wins on visual decisions, `PRODUCT.md` wins on voice: if you have both, variants stay on-brand without being told.

Try it
------

    /impeccable live

Open your dev server URL, pick the newsletter signup card, click the `delight` chip, hit Go. You will get three variants that vary across personality dimensions (a stamp-and-postcard feel, a typographic-surprise version, an illustrated-accent one), not three riffs on the same treatment.

Or pick a hero, type “more editorial, less SaaS”, hit Go. The three variants anchor to different editorial archetypes (broadsheet masthead, catalog-style spec rows, oversized-glyph poster) rather than three shades of the same idea.

Stop live mode when you are done: say “stop live mode”, close the tab, or hit the exit button on the picker bar.

Pitfalls
--------

*   **Running it on a page that is still half-written.** Live variant generation needs context. If the element has placeholder copy, generic Lorem ipsum, or pre-stylesheet default formatting, variants will reflect that. Fill the content first.
*   **Expecting it to make macro decisions.** Live mode iterates on a single picked element. For “redo the entire pricing page”, ask `/impeccable` directly instead.
*   **Ignoring the fallback messages.** If the element lives in a generated file (a compiled template, a build output), the picker says so explicitly and offers to route the accept into true source. Do not force the accept into the generated file: the next build will wipe it.
*   **Running it without PRODUCT.md or DESIGN.md when you care about brand fit.** Live will still generate, but the variants will lean toward generic defaults. Run `/impeccable init` and `/impeccable document` first if the result needs to sound like your product.
*   **Reaching for it on a native app.** Live drives a browser against your dev server, so it has nothing to attach to on an iOS or Android codebase. Impeccable will not offer it there. See [Design Context](https://impeccable.style/docs/context)
    .

---

# Design Context | Impeccable

[Skip to content](https://impeccable.style/docs/context#main)

Impeccable works best when it can read the same product and design decisions you would give a human designer. Without that context, it has to infer audience, tone, palette, type, and component rules from code alone. That usually produces safer, more generic answers.

If Impeccable gives you generic advice, the design context is usually missing, too vague, or stale.

The fast path
-------------

Run the setup once from your project root:

    /impeccable init

That creates `PRODUCT.md`, the strategy file. At the end, say yes when Impeccable offers to run:

    /impeccable document

That creates `DESIGN.md`, the visual-system file, plus a generated helper at `.impeccable/design.json`. Review the two markdown files. Edit anything that does not match the real product.

Strategy **PRODUCT.md** Platform, users, purpose, positioning, evidence, brand commitments.

Visual system **DESIGN.md** Colors, type, components, radii, design rules.

Per surface **.impeccable/surfaces/** One page's mode, job, proof sequence, and chosen direction.

Generated **.impeccable/design.json** Structured metadata for automation. Do not hand-edit.

Used by **Commands, hooks, detector, Live Mode** More specific edits, better audits, fewer false assumptions.

What goes where
---------------

| File | What it should answer | Update it when |
| --- | --- | --- |
| `PRODUCT.md` | What platform is this? Who is it for? What does the product do, and what claim could a neighbor not copy? What real evidence and brand commitments exist? | Platform, audience, positioning, purpose, constraints, evidence, or brand commitments change. |
| `DESIGN.md` | What colors, type stacks, component treatments, radii, elevation, and visual rules are allowed? | Palette, typography, components, tokens, spacing/radius scales, or design rules change. |
| `.impeccable/surfaces/*.md` | For one page or route: what mode is it, what job does it do, what proof does it show, and which direction was chosen? | Written by the work itself. Edit it when a page’s strategy changes. |
| `.impeccable/design.json` | What structured design data should automation use? | Do not edit it directly. Refresh it by running `/impeccable document`. |

The markdown files are the files you own. The generated JSON helps the detector, hooks, and Live Mode read the design system precisely.

Scope your request to one surface
---------------------------------

The judgment that changes Impeccable’s output most is what the visitor came to the page to **do**. It reads that from the surface you named, so the useful habit is naming one:

    /impeccable polish the marketing homepage
    /impeccable audit the billing settings

Those get different treatment because they are different jobs, not because you configured anything. A marketing page has to earn attention; a settings screen has to disappear. One project usually holds several kinds, which is why this is decided per surface rather than set once for the whole repo.

The four modes, and what each one changes

Impeccable names four, and picks from the surface in front of it:

*   **Persuade.** The visitor decides and acts: landing pages, marketing, campaigns, pricing. Design is the product, so it has to earn attention. Distinctive type, committed palette, image-led openings.
*   **Operate.** The visitor completes a task: app UI, dashboards, editors, admin, tools. Density, predictable controls, readable states, stable navigation, quieter motion. Brand lives in precise details.
*   **Read.** The visitor understands something: docs, guides, help, changelogs. Comprehension first, then a reading experience worth staying in.
*   **Experience.** The visitor is inside the work: portfolios, galleries, showcases. The artifact leads and the interface recedes.

The mode comes from the surface, **not from what the company sells**. A developer tool's landing page is still Persuade. A fashion house's documentation is still Read. A docs index is Read, not Persuade.

Name it explicitly only when a page is genuinely ambiguous. Once resolved, it is recorded in that surface's brief under `.impeccable/surfaces/`.

**Upgrading from v3?** Modes replace the old brand/product **register**. Brand maps to Persuade, product maps to Operate, and Read and Experience are the two cases the old split had nowhere to put.

A leftover `## Register` heading in `PRODUCT.md` is no longer read, and [doctor](https://impeccable.style/docs/doctor)
 will find it and offer to delete it. Worth accepting: a retired axis left in the file is the kind of thing that reads as still meaningful to the next person.

Native apps: iOS, Android, and adaptive (alpha)

If you build for the web, skip this. \`PRODUCT.md\` carries a `## Platform` line, and `/impeccable init` works the value out while it scans your project, asking only when the evidence is ambiguous. A missing field means `web`.

| Value | Means |
| --- | --- |
| `web` | A website or web app, including responsive mobile web. The default. |
| `ios` | A native iOS or iPadOS app. Loads the Apple HIG guidance. |
| `android` | A native Android app. Loads Material Design 3 guidance. |
| `adaptive` | One Flutter, React Native, or KMP codebase that genuinely adapts per OS. Loads both. |

On a native platform, `audit` and `adapt` run native passes covering VoiceOver, TalkBack, touch targets, and platform conformance instead of CSS.

**Native support is alpha.** Live Mode, the detector, and the design hook all read a browser or parse HTML, so they sit out on a native project. Mobile web stays `web`, and a native wrapper around a website does not make its design language native.

How context changes the output
------------------------------

With context loaded, Impeccable can:

*   preserve the right identity instead of “improving” it into something generic;
*   pick the right standard for the surface, whether that is a Persuade page that has to land or an Operate screen that has to disappear;
*   replace hardcoded visual choices with documented tokens and components;
*   flag drift, such as fonts, colors, or border radii outside `DESIGN.md`;
*   keep Live Mode variants aligned with the system instead of inventing new palettes.

The context does not replace judgment. Existing code still matters, and an intentional exception can be documented with a detector ignore. See [Config and ignores](https://impeccable.style/docs/config)
.

Keeping context fresh
---------------------

Use this rule:

| Change in the project | Run |
| --- | --- |
| New audience, positioning, product purpose, platform, evidence, or brand commitments | `/impeccable init` |
| New palette, type stack, component primitives, radius scale, or design rules | `/impeccable document` |
| A hook says `DESIGN.md` is newer than `.impeccable/design.json` | `/impeccable document` |
| One-off intentional detector finding | Add a narrow ignore with `/impeccable hooks ignore-value` or `npx impeccable ignores`. |
| You are not sure what has fallen behind | `/impeccable doctor` ([Doctor](https://impeccable.style/docs/doctor)<br>) |

Impeccable also checks these files at the start of a session and mentions what looks stale, at most once a week per project. [Doctor](https://impeccable.style/docs/doctor)
 is the same report on demand, with the expensive checks added.

Treat context files like any other design artifact: review them in code review when they change, and update them when the product changes.

Details when the default path is not enough
-------------------------------------------

Where Impeccable looks for context files

For normal projects, put `PRODUCT.md` and `DESIGN.md` in the project root.

Skill commands look in the root first. If root context is missing, they also check `.agents/context/` and `docs/`.

In a monorepo, each workspace child resolves its own `PRODUCT.md` and `DESIGN.md` first, then falls back to the repo root per file. Project boundaries come from package-manager workspace declarations, or from `projectRoots` globs in `.impeccable/config.json` when no package manager declares them. See [Config and ignores](https://impeccable.style/docs/config)
.

The detector's design-system rules use the same root-first behavior for `DESIGN.md`. For generated design metadata, the primary path is `.impeccable/design.json`. Legacy `DESIGN.json` files are still accepted as fallbacks, but new projects should use `.impeccable/design.json`.

What happens when docs and code disagree

`PRODUCT.md` wins on durable product and voice decisions: platform, audience, positioning, constraints, evidence, and brand commitments.

`DESIGN.md` wins on visual decisions: color, typography, radius, elevation, component behavior, and system-specific do/don't rules.

A surface brief in `.impeccable/surfaces/` wins on that one page's strategy: its mode, its job, the proof sequence, and the direction that was chosen for it.

Existing code still matters. Commands read project files before editing and preserve real conventions when they are stronger or newer than the docs. A stale `DESIGN.md` is a signal to refresh the docs, not permission to ignore the implementation.

Which detector rules unlock when DESIGN.md exists

When `DESIGN.md` exists, `npx impeccable detect` and the design hook unlock design-system checks:

*   `design-system-font` flags primary fonts not declared in `DESIGN.md` typography.
*   `design-system-color` flags literal colors outside the documented palette or sidecar ramps.
*   `design-system-radius` flags border-radius values outside the documented rounded scale.

These rules do not run when `DESIGN.md` is absent, when config disables design-system checks, or when you pass `--no-design-system` to the detector. See [Detector CLI](https://impeccable.style/docs/detector)
.

---

# Config and ignores | Impeccable

[Skip to content](https://impeccable.style/docs/config#main)

Impeccable stores runtime settings under `.impeccable/`. Most users do not need to hand-edit those files. Use the CLI when you want to record a confirmed exception.

Use config for:

*   detector ignores shared by `npx impeccable detect` and the design hook;
*   private local ignores that should not be committed;
*   hook lifecycle settings such as enabled, quiet mode, and audit logging;
*   project roots, for repos where design boundaries are not declared by a package manager.

Use `PRODUCT.md` and `DESIGN.md` for product and design intent. See [Design Context](https://impeccable.style/docs/context)
.

The usual path
--------------

List the current ignores:

    npx impeccable ignores list

Add the narrowest exception that matches the real reason:

    npx impeccable ignores add-value design-system-color "#ff00aa" --reason "Campaign accent"
    npx impeccable ignores add-file "src/legacy/**"
    npx impeccable ignores add-rule side-tab

Remove an exception when the underlying code is fixed:

    npx impeccable ignores remove-value design-system-color "#ff00aa"

The same detector config is used by the CLI and the hook, so an ignore behaves consistently in both places.

A config file fails quietly when it is wrong: a misspelled key is simply never read, an ignored rule id that no longer exists suppresses nothing, and a `projectRoots` glob that matches no directory leaves the repo root standing in for the app you meant. [/impeccable doctor](https://impeccable.style/docs/doctor)
 checks for all three. It also reads `"stalenessCheck": false` here, which turns off the session-start staleness notice.

Shared or local
---------------

Default ignores go into `.impeccable/config.json`. Commit them when they represent team intent: a legacy folder, a confirmed brand exception, or a project-wide rule decision.

Use `--local` for private work:

    npx impeccable ignores add-file "src/private-experiment/**" --local

Local settings go into `.impeccable/config.local.json`, which Impeccable keeps out of git.

Project Roots
-------------

Impeccable normally finds nested projects through package-manager workspace declarations: `package.json` workspaces, `pnpm-workspace.yaml`, or `lerna.json`. When those files do not exist, or when design boundaries do not line up with packages, declare the roots directly:

    {
      "projectRoots": ["docs/design/skins/*"]
    }

Each matched folder becomes its own project: it can carry its own `PRODUCT.md` and `DESIGN.md`, it appears in the app picker, and it falls back to the repo root per file for any context it does not define. See [Design Context](https://impeccable.style/docs/context)
.

How the patterns resolve against package workspaces

*   Patterns are relative to the repo root and use the same glob syntax as `package.json` workspaces, including `*`, `**`, and `!` negation.
*   `projectRoots` in `config.local.json` extends the shared list, so one developer can add private roots without committing them.
*   A path matched by any `projectRoots` pattern, positive or negated, is governed by this config alone. Package-manager workspaces apply only to paths these patterns do not match, and each source's `!` negations apply only to its own patterns. So `"!apps/internal"` here hides a package workspace from Impeccable, while a package-level negation never hides a folder that `projectRoots` declares.

Value ignores
-------------

Prefer value ignores when a rule reports a specific value:

    npx impeccable ignores add-value overused-font Inter --reason "Brand font"

Fonts, colors, radii, and motion values should usually be suppressed by value, not by whole rule. That keeps the rule useful everywhere else.

Wildcard value ignores are allowed only when scoped to a file:

    npx impeccable ignores add-value design-system-color "*" --file "src/demo.css"

That keeps one intentionally experimental file from teaching the whole project that every undocumented color is acceptable.

Inline ignore comments
----------------------

Config ignores live in `.impeccable/config.json`, which is the right home for repo-wide policy. They do not follow a file out of the repo, though. When a waiver belongs to one file and needs to travel with it (a generated or exported standalone document, an emailed HTML file, a snippet scanned out of context), put the waiver in the file itself:

    <!-- impeccable-disable overused-font: exported brand doc, font is first-party -->

The marker works in any comment syntax, and three scopes are available:

    /* impeccable-disable overused-font */            /* whole file */
    .brand { font-family: Inter }  /* impeccable-disable-line overused-font */
    /* impeccable-disable-next-line bounce-easing */

Syntax details and per-file behavior

The directive is comment-syntax-agnostic: the same marker works in `//`, `/* */`, `<!-- -->`, `#`, and `{/* */}` comments across HTML, CSS, JSX, TSX, Vue, and Svelte.

List one or more rule ids, comma-separated, or omit them (or use `*`) for every rule. A reason after `:` or `--` is optional and recommended; it is for the diff, and the scanner discards it.

Static HTML findings have no line number, so only whole-file `impeccable-disable` applies to them. That is the standalone-document case this exists for. The line-scoped forms apply to CSS, JSX, TSX, Vue, and Svelte, where findings carry a line.

Inline directives apply by default. `--no-inline-ignores` turns them off for one run while keeping config ignores; `--no-config` turns off config and inline ignores together.

Details when the default path is not enough
-------------------------------------------

What the config file looks like

The shared config lives at `.impeccable/config.json`. A typical file looks like this:

    {
      "detector": {
        "ignoreRules": [],
        "ignoreFiles": [],
        "ignoreValues": [],
        "designSystem": {
          "enabled": true
        }
      },
      "hook": {
        "enabled": true,
        "quiet": false,
        "auditLog": ".impeccable/hook.ndjson"
      }
    }

The `detector` section is shared by manual scans and hooks. The `hook` section only controls automatic hook execution and hook output.

Disable design-system checks

Design-aware rules run when `DESIGN.md` exists. Disable them for the project only when the design file is intentionally not authoritative yet:

    {
      "detector": {
        "designSystem": {
          "enabled": false
        }
      }
    }

For one manual run, keep config but skip the design-system rules:

    npx impeccable detect --no-design-system src/

Use `--no-config` only when you want a raw scan with no project ignores and no `DESIGN.md` context.

Hook runtime settings

Use `/impeccable hooks` for normal lifecycle changes:

    /impeccable hooks status
    /impeccable hooks on
    /impeccable hooks off

`hook.quiet: true` suppresses clean and pending acknowledgements while still surfacing new findings.

`hook.auditLog` writes one NDJSON line per hook invocation for debugging. Leave it off during normal work.

Environment variables still override config for one shell: `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, and `IMPECCABLE_HOOK_LOG`.

---

# animate | Impeccable

[Skip to content](https://impeccable.style/docs/animate#main)

Static layout → Choreographed entrance

When to use it
--------------

`/impeccable animate` is for interfaces that feel lifeless, where state changes are instant and jarring, where loading just pops in, where the user never quite trusts that their click registered. Use it to add the small motions that communicate what is happening: entrances, exits, feedback, transitions between states.

Do not use it to add bounces or elastic springs for the sake of energy. That is decoration, and this skill will not give it to you.

How it works
------------

The skill identifies static moments that would benefit from motion, then applies them with strict discipline:

1.  **Entrances and exits**: elements appear and leave with 200 to 300ms fades plus subtle Y or scale, never layout properties.
2.  **State feedback**: hover, active, focus, loading, success all communicate via motion instead of sudden swaps.
3.  **Transitions between views**: shared-element transitions where it makes sense, fade-through otherwise.
4.  **Progress and loading**: skeleton screens, determinate bars, motion that says “still working”.
5.  **Reduced motion**: every animation has a `prefers-reduced-motion` fallback.

Easing is always exponential (ease-out-quart, quint, or expo) because real objects decelerate smoothly. No bounce, no elastic, no linear for anything except progress indicators.

The skill animates `transform` and `opacity` only. If you find yourself animating `width`, `height`, `top`, or `left`, it is doing the wrong thing. Use `grid-template-rows` for height transitions.

Try it
------

    /impeccable animate the sign-up flow

Typical additions:

*   Email input gets a focus glow on focus-visible (opacity + shadow, 180ms)
*   Submit button shows a spinner inside itself on loading state, not a separate spinner next to it
*   Success screen enters with opacity + translateY(8px), 260ms, ease-out-quart
*   Error message slides down with grid-template-rows (not height), 220ms
*   `@media (prefers-reduced-motion: reduce)` fallback for every transition

Pitfalls
--------

*   **Asking for “more animation”.** Animate is not a dial. It adds where motion communicates, not everywhere.
*   **Removing the reduced-motion fallbacks.** The skill adds them automatically. Non-negotiable for accessibility.

---

# Doctor | Impeccable

[Skip to content](https://impeccable.style/docs/doctor#main)

v4 changed what `PRODUCT.md` holds and retired the brand-or-product register field, so a project set up under v3 can be carrying answers the current version no longer reads. Nothing used to measure that. Now two things do.

You get told at the start of a session
--------------------------------------

Impeccable checks its own files when a session begins and mentions what it finds, once:

*   a product record written before v4,
*   a design sidecar older than the `DESIGN.md` it extends,
*   a config key that is a near-miss of a real one and has therefore never applied to anything,
*   an app that ships to iOS or Android while inheriting a record that says web.

That last one is the most valuable catch, because it costs you quality quietly rather than failing loudly.

None of it blocks the work you asked for. A given finding is raised **at most once a week per project**, so something you decided to live with does not come back tomorrow.

Ask for the full picture
------------------------

    /impeccable doctor

The boot check is deliberately cheap: it looks only at files a session already reads. `doctor` runs the deep pass and adds the checks that cost real work, like how much interface code has shipped since `DESIGN.md` was last touched, whether the detector rules you ignored still exist, and whether your design hook’s script path still resolves.

Ask it in plain language too. “What’s out of date here?” gets you the same report.

### It fixes what it can and hands over the rest

Findings come in three kinds, and the kind tells you what happens rather than how bad it is:

| Kind | What Impeccable does |
| --- | --- |
| Mechanical | Repairs it, then tells you in one line. No decision to make. |
| Worth knowing | States it once, with the fix on offer. |
| Needs a command | Names `init` or `document` and the specific gap it would close. |

That last split is the point. A file whose _schema_ is old is a migration. A file that no longer _describes your code_ is a conversation, so doctor hands it to the command that owns it with the gap named, instead of quietly rewriting your product record.

An empty report is the good outcome, and it says so in one line.

Deeper
------

Three kinds of "out of date", and which one this owns

They get conflated constantly, and only one of them is this command's job:

*   **Tool version.** Your installed skill is older than the published one. Reported separately at boot; `npx impeccable update` fixes it.
*   **Schema drift.** An artifact was written by an older Impeccable: fields nothing reads, fields now expected, files in retired locations. Mechanical, and doctor repairs most of it. **This is what doctor owns.**
*   **Truth drift.** Your code moved on and the document no longer describes it. No file comparison settles this, which is why it gets routed to [init](https://impeccable.style/docs/init)
     or [document](https://impeccable.style/docs/document)
     rather than repaired.

What it actually checks

**PRODUCT.md** carries a schema stamp, so the checks read a file's vintage rather than guessing it from which sections it happens to have. It is a schema version, not a release version: a record written by 4.0.0 is not stale under 4.0.1. `DESIGN.md` gets no stamp, because it follows the external design.md spec rather than Impeccable's own.

**The design sidecar** (`.impeccable/design.json`) is checked for being older than the `DESIGN.md` it extends, for an outdated schema, and for sitting at a legacy path.

**Config** is checked for unknown keys, unknown detector keys, ignored rule ids that no longer exist in the rule registry, ignored file paths that are gone, and `projectRoots` globs that match no directory.

**The design hook** is checked for a script path that stopped resolving and for an enabled/disabled conflict. A hook whose path broke looks installed while scanning nothing, which is exactly the failure you would never notice.

**Surface briefs** are checked for records orphaned from the file or route they describe.

If the rule registry cannot be reached, doctor says the ignored-rule list could not be validated rather than implying it is clean.

Why a big number is not a verdict

One check counts commits to your visual source directories since `DESIGN.md` was last edited. A commit count is not a contradiction, and doctor will not tell you your design system is stale because the number looks large. It reports the number and says what it measures. If you want to know whether the document is actually wrong, ask, and it reads `DESIGN.md` against your current tokens and components.

The same restraint applies to a workspace inheriting the root's context. Inheritance is designed behavior, not a defect. Whether one product record truthfully describes several apps is your call.

Monorepos

Pass the app you mean. Without it the report describes the repo root, which in a monorepo is usually the wrong project.

You also get a table of which apps carry their own `PRODUCT.md` and `DESIGN.md` and which inherit the root's, before anything is proposed.

The finding that matters most here is a workspace carrying native build files while inheriting a root record that resolves to web: that app gets web guidance for its entire life and never loads the iOS or Android rulebook. The repair is a child `PRODUCT.md` in that workspace, because one inherited record cannot hold two platforms.

Turning the boot check off

Set `"stalenessCheck": false` in `.impeccable/config.json` to silence the session-start notice for the project, or `IMPECCABLE_NO_STALENESS_CHECK=1` for a single session.

`/impeccable doctor` still works with the check disabled. That combination is the one to use if you want the report only when you ask for it.

Related
-------

*   [Design Context](https://impeccable.style/docs/context)
     for what belongs in each file doctor checks.
*   [Config and ignores](https://impeccable.style/docs/config)
     for the keys and ignore lists it validates.
*   [Design hooks](https://impeccable.style/docs/hooks)
     for the hook it verifies is really running.

---

# Detector CLI | Impeccable

[Skip to content](https://impeccable.style/docs/detector#main)

`npx impeccable detect` runs Impeccable’s deterministic design checks directly from the terminal. Use it when you want a fast signal without asking an AI command to review the work.

Fast path
---------

Scan the source folder:

    npx impeccable detect src/

Scan one file:

    npx impeccable detect src/components/Card.tsx

Scan a rendered page:

    npx impeccable detect https://example.com

Use JSON when another script or CI job needs to read the result:

    npx impeccable detect --json src/

What it checks
--------------

The detector looks for design and implementation patterns that are usually visible to users: contrast problems, typography drift, layout overflow, generic AI-design tells, brittle motion, and design-system violations when `DESIGN.md` exists.

Directories are walked for design-relevant files. HTML files include linked local CSS. Framework files such as JSX, TSX, Vue, Svelte, Astro, and CSS modules get source-text checks. URL targets use a browser and inspect the rendered page.

Server-side templates are covered too, once you name their extensions. Add them under `detector.extensions` in `.impeccable/config.json` and Blade, ERB, Twig, or Handlebars files get the same checks as JSX. See [Config and ignores](https://impeccable.style/docs/config)
.

**Web only.** The engine reads HTML and CSS, so it has nothing to say about a native iOS or Android codebase. On a project whose `PRODUCT.md` declares `ios`, `android`, or `adaptive`, use `/impeccable audit`, which runs a native pass covering VoiceOver, TalkBack, touch targets, and platform conformance instead.

How to read results
-------------------

Plain output groups findings by file and prints the rule id, snippet, and explanation. Exit codes are:

| Code | Meaning |
| --- | --- |
| `0` | No findings. |
| `2` | Findings were detected. |
| `1` | The command failed. |

That makes CI usage straightforward: fail the job on `2`, then decide whether to fix the issue or add a narrow ignore.

DESIGN.md awareness
-------------------

When a local `DESIGN.md` exists, `detect` loads it by default and enables design-system checks for fonts, literal colors, border radii, and literal font sizes documented in the typography ramp. The generated `.impeccable/design.json` sidecar gives those checks richer token and ramp data.

If the design file is stale, refresh it:

    /impeccable document

If you need one scan without design-system checks:

    npx impeccable detect --no-design-system src/

To narrow a scan to one design domain (for example before a typeset or layout pass):

    npx impeccable detect --scope type src/
    npx impeccable detect --scope layout src/

Managing intentional findings
-----------------------------

Detector ignores are shared with the design hook:

    npx impeccable ignores list
    npx impeccable ignores add-value overused-font Inter --reason "Brand font"
    npx impeccable ignores add-file "src/legacy/**"

For a waiver that should travel with one file instead of living in the repo config, drop an inline comment in the file itself:

    <!-- impeccable-disable overused-font: exported brand doc -->

Use [Config and ignores](https://impeccable.style/docs/config)
 for the full ignore workflow, including the line-scoped `impeccable-disable-line` and `impeccable-disable-next-line` forms.

Details when the default path is not enough
-------------------------------------------

Scan stdin

If you pipe text into the command with no target, it scans stdin:

    cat component.css | npx impeccable detect

Project config and raw scans

By default, `detect` reads `.impeccable/config.json` and `.impeccable/config.local.json`.

It respects `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`.

It does not respect `hook.enabled`; manual scans still run when the automatic hook is disabled.

In-file `impeccable-disable*` comments are honored too, so a waiver can travel with a file. `--no-inline-ignores` skips just those; `--no-config` skips config and inline ignores together.

Use `--no-config` only when you want a raw detector run with no project config, no detector ignores, and no `DESIGN.md` context.

Where the detector fits

The same detector also powers the design hook, `/impeccable audit`, the public [slop catalog](https://impeccable.style/slop)
, the browser extension, and the local detector lab.

Use [Design hooks](https://impeccable.style/docs/hooks)
 when you want findings inside the agent flow. Use `detect` when you want a direct terminal signal.

---

# delight | Impeccable

[Skip to content](https://impeccable.style/docs/delight#main)

Milestone reached

100

tasks completed

Dismiss

🎊 ✨ 🎉 ✨ 🎊

Milestone unlocked!

100

tasks completed

🏆 Centurion Badge Earned

Functional feedback → Moment of joy

When to use it
--------------

`/impeccable delight` is for interfaces that work but do not feel like anything. Use it when the core experience is solid and you want to add the small human touches that make people remember it: a considered empty state, a loading message with a point of view, a success animation that feels earned, a microcopy moment that makes someone smile.

It is a finishing skill. Never the first thing you run on a new build.

How it works
------------

The skill hunts for delight opportunities in the places most designers skip:

1.  **Empty states**: instead of “No items yet”, something with personality appropriate to the brand.
2.  **Loading and waiting moments**: the best products turn waits into content.
3.  **Success feedback**: a moment of celebration when something worth celebrating happens.
4.  **Microcopy**: button labels, tooltips, error messages, placeholder text. Tiny copy with taste.
5.  **Easter eggs and secondary states**: things users discover that reward paying attention.

The skill reads the brand tone from `PRODUCT.md`. A serious analytics tool gets serious delight (dry, precise, a little clever). A playful consumer app gets more overt personality. It does not force humor where humor is wrong for the audience.

The rule is: every delight moment must still work perfectly if you delete the delight. Nothing depends on the smile.

Try it
------

    /impeccable delight the first-run experience

Expected additions:

*   Empty dashboard replaces “No data yet” with “Your dashboard is quiet. Let’s fix that.” plus a single-action CTA.
*   Initial sync gets a 3-state loading message that advances: “Finding your accounts… / Pulling the last 30 days… / Making it look good…”.
*   First successful action triggers a one-time toast with a tiny celebratory moment. After that, just a quiet checkmark.
*   Help tooltip on the tricky field has a voice that sounds like a person wrote it.

Pitfalls
--------

*   **Forcing humor.** Not every brand is playful. If the brand voice in `PRODUCT.md` is “clinical and precise”, delight adds clever restraint, not jokes.
*   **Over-decorating.** One moment of delight is memorable. Twenty becomes noise. The skill is conservative on purpose.
*   **Running delight before polish.** Polish fixes what is wrong. Delight adds what is missing. In that order.

---

# New work | Impeccable

[Skip to content](https://impeccable.style/docs/new-work#main)

There is no command for building something new. Describe it and Impeccable takes it from there:

    /impeccable a pricing page for enterprise customers
    /impeccable redesign the marketing site
    /impeccable add a comparison table to the pricing page

It works out which of those you meant, and how much is allowed to change. A redesign replaces the look. An addition inherits the page it joins. You do not have to say which.

Coming from v3? This is what `/impeccable craft` used to be. The alias still works and adds nothing.

The one decision that is yours
------------------------------

Partway in, Impeccable stops and asks you to pick a **direction**: a visual world plus a concrete plan for the first screen. In an attended session it opens a page in your browser with the direction it landed on, alternates beside it, and two controls.

*   **Deal again.** Not right? Re-roll, as often as you like. Every direction already shown is off the table, so nothing comes back reworded.
*   **Steer.** One line about what is missing (“too corporate”, “needs to feel like print”) and the next round honors it.

Rejecting everything is a valid answer. Nothing gets built until you pick.

If your harness cannot open a browser, the same choice arrives as a normal question prompt.

### Your brief always wins

If you name an era, a material, a typeface, or a palette, that beats whatever Impeccable would have chosen:

    /impeccable a landing page for our vinyl shop, 1970s hi-fi catalog look, Futura

It will not talk you out of that. The direction machinery exists for when you have not said, not to override you when you have.

It shows you the design before it builds it
-------------------------------------------

Once you pick, Impeccable renders the direction as a system board (palette, type, components) and a mock of the first screen, then builds toward that image instead of a paragraph of adjectives. Seeing it first measurably improves the result.

This works out of the box on harnesses with a built-in image tool, like Codex or Gemini CLI. Without one, set an OpenAI key and you get the same thing:

    export OPENAI_API_KEY=sk-...

It renders through gpt-image-2 and tells you it is spending your credit before the first image, roughly 5 to 25 cents each. The mock is a reference, not a spec: real copy, responsiveness, and accessibility stay implementation decisions, and no image is left behind in your repo.

What it writes down
-------------------

*   **`DESIGN.md`** gets the visual system when the work established a new one, refreshed after the build so it holds the values the code actually uses.
*   **`.impeccable/surfaces/<page>.md`** gets that page’s strategy: who it is for, what it must prove, and the direction that won. A later session picks up the argument instead of inventing a new one.

An addition to an existing page changes neither without asking.

Why any of this exists
----------------------

Ask a coding model for something creative and it builds its favorite idea, every run. Sixteen different “be creative” framings returned the identical concept in thirty of thirty-five runs. It is not a shortage of creativity, it is a shortage of variance: one model has one taste function, so its top-ranked idea always wins.

So the ranking gets broken from outside. A roll decides which of the model’s own ideas has to be taken seriously, and deals challengers from a reviewed catalog of 188 visual worlds to compete against them. [The research](https://impeccable.style/research)
 has the full account.

Challengers are not templates and never get applied as one. Each has to survive translation into your product first, and most lose to a strong idea derived from the product itself. That is the intended outcome.

Deeper
------

How it decides what kind of job this is

The classification comes first, because it sets how much freedom the work has:

*   **Greenfield.** No coherent visual implementation exists. A world gets established.
*   **Local extension.** A section or component inside a page that already works. Only the new part gets decided; the page's world is inherited.
*   **New surface.** A whole page or flow inside an established world. Composition is open, the world is not.
*   **Expression expansion.** An established brand entering a surface family it never resolved. You approve a range, which is merged into `DESIGN.md`.
*   **Redesign or rebrand.** The look is replaced. Product facts, content, function, and constraints are not.
*   **Refinement.** Better, not different. Leaves this flow for a scoped command like [polish](https://impeccable.style/docs/polish)
    .

Two of these get confused constantly. "Redesign this page" authorizes replacement: the old look becomes evidence and anti-reference. "Redesign this within our current system" is an extension. Impeccable asks once when the wording is genuinely ambiguous, and never splits the difference into polishing a look you asked to be rid of.

What counts as your existing design system

Before proposing anything, Impeccable reads `DESIGN.md`, your tokens, your components, and real assets.

**A missing `DESIGN.md` does not make a project greenfield.** Coherent code, type choices, and component behavior are authority whether or not anyone wrote them down. Scaffolds, framework defaults, and stray utility classes are not.

If your implementation is coherent but undocumented, Impeccable extracts the invariants, confirms them with you, and writes `DESIGN.md` before going further. It will not offer you replacement worlds unless you asked for a redesign.

How a direction has to earn its place

Every candidate, whether the model derived it or the roll dealt it, faces five tests. Failing one is fatal no matter how well it does on the others.

*   **Truth.** Every relationship it visualizes exists in your product. Resemblance is not evidence.
*   **Translation.** Strip the source's names and materials and a product-native relationship remains. Otherwise it is a costume.
*   **Consequence.** Removing its best move materially weakens the page. Otherwise it is ordinary craft with a story attached.
*   **Survival.** The signature still works on the primary device, within a real asset and time budget.
*   **Fit.** Its risk is an honest tradeoff, not a probable violation of your brief.

A candidate still explained by its source object has not been translated, and it loses.

The direction contract, and reproducing a roll

Before writing code, the agent states the direction as a comment at the top of the artifact: at most 150 words across five blocks.

*   `THESIS`: the one idea this page owns, and the category default it refuses.
*   `OWN-WORLD`: the palette and component language, specific enough to recognize with all content removed.
*   `STORY`: what the visitor understands, believes, and does.
*   `FIRST VIEWPORT`: the exact composition and where the primary action sits.
*   `FORM`: the chosen form and the seed key.

It is there so intent is inspectable and so the finishing review can audit the built page against it promise by promise, in a separate agent where your harness allows one. A page that promised a radical composition and shipped the usual template does not pass quietly.

Keep the seed key if you want to reproduce a roll later. It replays the whole thing, including every re-roll round.

Who may re-roll, and on what grounds

You re-roll freely and for any reason, including taste. After two in a row, Impeccable asks what quality is missing rather than guessing at a third.

The agent may only re-roll on named factual grounds: the assigned direction cannot carry the product's truth or the task. Its own taste is never grounds, which is the whole point of rolling from outside its ranking.

In an unattended run there is nobody to ask, so the assigned direction proceeds and the assumptions get stated explicitly.

Related
-------

*   [Design Context](https://impeccable.style/docs/context)
     for the files this reads and writes.
*   [`/impeccable shape`](https://impeccable.style/docs/shape)
     to stop at the brief, with no code.
*   [The research](https://impeccable.style/research)
     for the measurements behind the roll.

---

# Design hooks | Impeccable

[Skip to content](https://impeccable.style/docs/hooks#main)

The design hook runs Impeccable’s detector automatically when an AI coding tool edits UI files. It catches regressions while the agent still has the edit in context.

Fast path
---------

Check hook state inside your AI tool:

    /impeccable hooks status

Turn the hook on or off for this project:

    /impeccable hooks on
    /impeccable hooks off

Installer and updater commands can skip hook setup for one run:

    npx impeccable install --no-hooks
    npx impeccable update --no-hooks

What it does
------------

The hook scans direct edits to UI code and styles. When it finds a new issue, it sends the agent a short reminder with the finding and a fix direction.

Claude Code, GitHub Copilot, and Codex run after the edit. Cursor checks proposed writes before they land and blocks only when the detector finds an issue in the proposed UI code.

Plain `.ts` and `.js` files are scanned, but the hook stays quiet unless it finds something design-relevant.

### Two speeds

The hook does not report everything on every edit. You get two passes instead:

*   **Per edit:** only what is objectively broken or compounds if ignored. Broken images, overflowing and clipped text, contrast failures, tiny text, gradient text, glow, and drift from your own `DESIGN.md`.
*   **At the end of the session:** the full rule set across every UI file you touched, minus anything already reported.

Why it is split, and how to turn the split off

Reporting every rule on every edit made models measurably more conservative rather than more careful. One copy-level rule alone fired about ninety-seven times in a single session, and the findings that get fixed well (contrast, padding, glow) are the ones judged against a finished page, not a half-written one.

The deep pass fires once per session; a second stop is silent, because its findings are remembered.

Set `hook: { "perEditRules": "all" }` in `.impeccable/config.json` to get every rule on every edit again. Cursor and GitHub Copilot are exempt from the split, since they have no end-of-session pass wired and nothing should be deferred into a pass that never runs.

**Web only.** The hook parses HTML and CSS, so it does not run on a project whose `PRODUCT.md` declares `ios`, `android`, or `adaptive`. See [Design Context](https://impeccable.style/docs/context)
.

### Checking it is really running

A hook can look installed and scan nothing: if its script path stops resolving, after a move or a reinstall, the manifest still registers and no findings ever arrive. Silence reads as a clean codebase.

[`/impeccable doctor`](https://impeccable.style/docs/doctor)
 checks for exactly that, along with a manifest that says enabled while config says otherwise. Worth running once after you move a project.

Handling intentional findings
-----------------------------

Persist an exception only after you confirm the finding is intentional. Prefer the narrowest exception:

    /impeccable hooks ignore-value overused-font Inter --shared --reason "Brand font"
    /impeccable hooks ignore-file "src/legacy/Card.tsx"
    /impeccable hooks ignore-rule side-tab

For value-specific rules such as `overused-font`, use `ignore-value` for a specific font. Use `ignore-rule overused-font --all-values` only when you want to suppress the entire rule.

The terminal equivalent is `npx impeccable ignores ...`, which writes the same detector config. See [Config and ignores](https://impeccable.style/docs/config)
.

Details when the default path is not enough
-------------------------------------------

Supported harnesses and approval steps

`npx impeccable install` and `npx impeccable update` install provider-native hook manifests for Claude Code, GitHub Copilot, Codex, and Cursor.

*   Claude Code: `.claude/settings.local.json` by default.
*   GitHub Copilot: `.github/hooks/impeccable.json`, a committed file shared by the Copilot CLI and the cloud agent.
*   Codex: `.codex/hooks.json`.
*   Cursor: `.cursor/hooks.json`.

GitHub Copilot reads the committed `.github/hooks/impeccable.json`. In the Copilot CLI the hook activates once that file is on the repository's default branch and you trust the folder; the cloud agent reads it straight from the repo.

Codex requires one extra approval step. After install or update, open `/hooks` in Codex and approve the project hook. Codex tracks trust by hook definition, so updates can require approval again.

Cursor users should also confirm hooks are enabled in Cursor Settings -> Hooks.

Scanned file types

The hook scans common UI and style files:

`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, and `.js`.

Config and environment overrides

Hook lifecycle settings live under `hook` in `.impeccable/config.json`:

    {
      "hook": {
        "enabled": true,
        "quiet": false,
        "auditLog": ".impeccable/hook.ndjson"
      }
    }

Per-developer choices, including install consent, live in `.impeccable/config.local.json`.

Detector filters live under `detector`, not `hook`, because they are shared by the hook and the CLI detector.

Environment variables still override config for one shell: `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, and `IMPECCABLE_HOOK_LOG`.

Debugging hook behavior

Start with status:

    /impeccable hooks status

It shows the shared and local config paths, current ignores, hook state, and relevant environment overrides.

For invocation logs, set `hook.auditLog` or use `IMPECCABLE_HOOK_LOG`. The hook writes one NDJSON line per invocation. Leave audit logging off for normal work.

If a manifest is malformed, install/update aborts by default. Re-run with `--force` only when you want Impeccable to back up the malformed file as `.bak` and replace it.

---

# document | Impeccable

[Skip to content](https://impeccable.style/docs/document#main)

DESIGN.md Google Stitch format

01 Overview

Creative North Star: _"The Editorial Sanctuary."_ Quiet type, generous air, one committed accent.

02 Colors

03 Typography

Aa Cormorant Garamond · Instrument Sans

04 Elevation

Flat by default. Shadows appear only as a response to state.

05 Components

Subscribe filter card

06 Do's and Don'ts

Tint neutrals toward the accent hue. Gradient text for emphasis.

The six sections are fixed, in a fixed order, with fixed names. Alongside, `.impeccable/design.json` ships as a machine-readable sidecar for tools that need structured design metadata.

When to use it
--------------

Run `/impeccable document` once you have enough of a visual system to document: colors, typography, at least a button and a card. The command scans your codebase, extracts the tokens and component patterns it finds, and writes a `DESIGN.md` at the project root that follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/overview/)
, six sections in a fixed order, interoperable with every other DESIGN.md-aware tool.

Reach for it when:

*   **You just ran `/impeccable init`** and `PRODUCT.md` now exists. Document is the matching visual-side file.
*   **A command nudged you toward it.** Live, polish, and the new-work flow all read DESIGN.md. If it is missing, the skill suggests running document first.
*   **The design has drifted** from an older DESIGN.md and the file no longer describes the live system.
*   **Before a large redesign**, to capture current state as a reference for the next direction.

How it works
------------

It reads your code, extracts everything it can on its own, and then asks one grouped question about the parts a scan cannot infer: what the system is _for_. That includes a named metaphor for the whole thing (something like “The Editorial Sanctuary”), descriptive color names, and the character your components are meant to have.

You get a `DESIGN.md` you can read and edit, plus a generated `.impeccable/design.json` sidecar that lets Live Mode and the design-aware detector rules check work against your real palette, type, and radii.

Every other command reads `DESIGN.md` on invocation, so variants, polishes, audits, and new surfaces inherit the visual system without being told. See [Design Context](https://impeccable.style/docs/context)
 for how the files relate.

Where it looks, and the exact file shape

The scan checks sources in priority order: CSS custom properties, Tailwind config, CSS-in-JS themes, design token files, component source, the global stylesheet, and finally computed styles from the rendered page if a browser is available.

The output has exactly six sections: Overview, Colors, Typography, Elevation, Components, and Do's and Don'ts. The headers are fixed character-for-character so other tools can parse the file.

No code yet? Use seed mode

On a fresh `init` with nothing built, `/impeccable document --seed` asks five quick strategic questions (color strategy, type direction, motion style, references, anti-references) and writes a scaffold. Re-run it in normal scan mode once there is code to read.

Try it
------

    /impeccable document

On a project with tokens already defined, this takes about two minutes: the scan finds your palette and type stack, you pick a North Star from 2 or 3 options, confirm descriptive color names (“Deep Muted Teal-Navy”, not “blue-800”), and the file lands at the project root.

On a fresh project:

    /impeccable document --seed

Five questions, about five minutes. The file is a scaffold, marked with a `<!-- SEED -->` comment so it is honest about what it is. Re-run without the flag once you have implemented tokens.

Pitfalls
--------

*   **Running it too early.** On a project with no implemented tokens, seed mode is right. Do not fabricate a full spec the code cannot back up. A fake DESIGN.md is worse than no DESIGN.md.
*   **Treating DESIGN.md as documentation for humans only.** It is primarily for the AI. Every other command reads it. The format’s forcefulness (“never”, “always”, Named Rules) is intentional.
*   **Adding a Layout / Motion / Responsive top-level section.** The spec has six sections, in a fixed order, with fixed names. Fold layout or motion content into Overview (philosophy-level rules) or Components (per-component behavior).
*   **Overwriting an existing DESIGN.md silently.** Document always confirms first. If you want to start fresh, rename the existing file out of the way or explicitly tell the skill to overwrite.

---

# init | Impeccable

[Skip to content](https://impeccable.style/docs/init#main)

PRODUCT.md Loaded on every command

Platform web

Users SREs on call, reading fast, often in the dark.

Positioning Traces every alert back to the deploy that caused it.

Evidence on hand Real incident timelines. No customer logos yet, do not invent any.

Every command reads this before writing a line of code.

A finished PRODUCT.md. Strategy only: who, what, why. No colors, no fonts, no pixel values, those live in DESIGN.md.

When to use it
--------------

Run `/impeccable init` once at the start of a project. Without it, every other command has to guess: generic SaaS voice, safe-default fonts, the AI color palette. With it, every command reads your answers before it generates.

Reach for it when:

*   **You just installed Impeccable in a new project.** First thing to run. Other commands will nudge you toward it if you skip.
*   **The project’s brand direction has shifted.** New positioning, new audience, new voice. Re-run `init` and the updated context flows through every command.
*   **Another command said “no design context found”** and stopped. That is the signal: run init, then resume.

How it works
------------

One codebase scan feeds everything init writes:

*   **`PRODUCT.md`** is the strategic file. Platform, users and their situation, product purpose, positioning, operating context, capabilities and constraints, brand commitments, evidence on hand, design principles, and accessibility needs. Answers “who, what, why”.
*   **`DESIGN.md`** is the visual file. Colors, typography, elevation, components, do’s and don’ts. Answers “how it looks”. Written by the delegated `/impeccable document` command, which init invokes at the end.
*   **Live mode config.** Since the same crawl already knows your framework and entry files, init pre-configures `/impeccable live` so it opens straight into variant mode with no first-time setup.

The flow scans the codebase first (README, package.json, components, tokens, brand assets) and turns that into a hypothesis rather than a questionnaire. It forms its own read of the platform (`web`, `ios`, `android`, or `adaptive`) and asks only when the evidence is genuinely ambiguous, so most projects never answer a platform question at all.

Then it asks what the repository could not tell it, at most three questions per round:

*   who the primary user is, in what situation, doing what job;
*   what the product makes possible, and the mechanism or claim a neighboring product could not truthfully copy;
*   what durable constraints, assets, evidence, or product facts future work must preserve.

Init deliberately does **not** ask for an aesthetic direction: no colors, no typography, no visual references. Those decisions belong to the design work itself, where the surface, its mode, and the direction roll all get a say. If you volunteer a binding visual constraint, init records it without expanding on it.

PRODUCT.md is strategic only. No colors, no fonts, no pixel values. Those live in DESIGN.md. Keeping the two files separate is deliberate: strategy can stay stable while the visual system evolves. See [Design Context](https://impeccable.style/docs/context)
 for the full load order and how the files interact.

It closes by pointing you at the best commands to run next, picked from what the scan turned up: `shape` to plan new work, `critique` or `audit` for what is already there, `live` to iterate visually. For a build, you can simply describe what you want and Impeccable routes it through the new-work flow. No guessing where to begin.

Try it
------

    /impeccable init

Expect a short interview, usually one round of two or three questions. Init quotes back what it inferred from your code (“from the routes and the Swift package, this reads as an iOS app, match?”) so you are confirming rather than starting from scratch.

Along the way it offers to run `/impeccable document` for you. Say yes unless you have a specific reason to hold off. A real DESIGN.md is what keeps variants, polishes, and audits on-brand.

Pitfalls
--------

*   **Skipping it to “just try a command quickly”.** Every other command will interview you mid-flight instead. Running init first is faster, not slower.
*   **Giving generic answers.** “It helps teams collaborate” is not useful. “It traces every alert back to the deploy that caused it” is. The positioning line is the one future work leans on hardest.
*   **Treating PRODUCT.md as immutable.** The file is yours. If init put something in there that is not quite right, edit it. Every command reads the current file.
*   **Expecting it to ask about visuals.** It will not, on purpose. Colors, type, and references belong to the design work, where the surface and its direction are decided together.
*   **Claiming evidence you do not have.** The Evidence on Hand section exists so later work knows what is real. State the absences too, and nothing downstream will invent a customer logo or a fake metric.

---