mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-21 02:26:31 +03:00
Consolidate 18 skills into 1 /impeccable skill with 20 commands
Biggest change in a while. Users previously had 18 standalone skill
entries cluttering their /menu; now they have one entry (/impeccable)
that routes to 20 specialized commands via argument dispatch. The pin
mechanism (/impeccable pin audit) restores standalone shortcuts on
demand for commands users hit all the time.
## Architecture
- Single /impeccable skill with command router section in SKILL.md
- 20 commands served via reference files under source/skills/impeccable/reference/
- /impeccable pin <command> creates a lightweight redirect shim so users
who prefer /audit, /polish, etc. can still have them
- Context gathering (teach) auto-runs on first use
- command-metadata.json is the single source of truth for command
descriptions, argument hints, and relationships
## Site rewrite
- Docs URL: /skills renamed to /docs (with /skills permanent redirects)
- Homepage hero frames Impeccable as "one skill with 20 commands"
- "Get Started" split into 50/50 install + how-to-use with editorial
numbered steps, /impeccable shown as the home command with three modes
- New /docs overview: home command hero card + dense category rows
matching the old cheatsheet density, with leads-to/pairs-with/
combines-with relationship metadata served from a shared source
- Cheatsheet merged into /docs, /cheatsheet redirects
- Magazine spread and mobile cards show /impeccable as a stacked
namespace label above the command name at full display size
- Periodic table updated with craft/teach/extract as first-class cells
- Skill detail pages generate from reference files, with an editorial
wrapper per command for tagline + body
- Tutorials and anti-patterns pages updated to use /impeccable <cmd>
## Build system
- Dead code removed (scripts/lib/transformers/shared.js)
- Build log wording fixed ("1 skill" not "1 skills (1 user-invocable)")
- generateApiData fallback branch removed (throws loudly if metadata
missing instead of silently degrading)
- Commands API includes editorial tagline alongside the long description;
UI surfaces prefer tagline for human display, description for auto-
trigger keyword matching
## Gitignore
- Added .claude/scheduled_tasks.lock, .claude/settings.local.json to
ignore list (local Claude Code state that should not be tracked).
- Harness skill directories (.claude/skills/, .agents/skills/, etc.)
remain tracked by design: npx skills reads them from this repo at
install time and they enable clean submodule use.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
f957fcad20
commit
b0f44f83c6
@@ -75,7 +75,7 @@ export const LAYER_LABELS = {
|
||||
export const LAYER_DESCRIPTIONS = {
|
||||
cli: 'Deterministic. Runs from `npx impeccable detect` on files, no browser required.',
|
||||
browser: 'Deterministic, but needs real browser layout. Runs via the browser extension or Puppeteer, not the plain CLI.',
|
||||
llm: 'Not caught by any deterministic detector. Flagged by /critique during its LLM design review.',
|
||||
llm: 'Not caught by any deterministic detector. Flagged by /impeccable critique during its LLM design review.',
|
||||
};
|
||||
|
||||
// ─── Visual examples ─────────────────────────────────────────────────
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
<div class="site-header-right">
|
||||
<nav class="site-header-nav" aria-label="Primary">
|
||||
<a href="/" data-nav="home">Home</a>
|
||||
<a href="/skills" data-nav="docs">Docs</a>
|
||||
<a href="/docs" data-nav="docs">Docs</a>
|
||||
<a href="/anti-patterns" data-nav="anti-patterns">Anti-Patterns</a>
|
||||
<a href="/visual-mode" data-nav="visual-mode">Visual Mode</a>
|
||||
</nav>
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Make designs work across screens, devices, and contexts without amputa
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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.
|
||||
`/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.
|
||||
|
||||
@@ -22,7 +22,7 @@ The non-negotiable rule: adapt, do not amputate. Critical functionality cannot d
|
||||
## Try it
|
||||
|
||||
```
|
||||
/adapt the settings page for mobile
|
||||
/impeccable adapt the settings page for mobile
|
||||
```
|
||||
|
||||
Expected changes:
|
||||
@@ -37,4 +37,4 @@ Expected changes:
|
||||
|
||||
- **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 `/harden` afterward.** Responsive layouts reveal edge cases. Run hardening after adapt to catch the ones that only show up at 320px.
|
||||
- **Skipping `/impeccable harden` afterward.** Responsive layouts reveal edge cases. Run hardening after adapt to catch the ones that only show up at 320px.
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Purposeful motion that conveys state, not decoration."
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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.
|
||||
`/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.
|
||||
|
||||
@@ -25,7 +25,7 @@ The skill animates `transform` and `opacity` only. If you find yourself animatin
|
||||
## Try it
|
||||
|
||||
```
|
||||
/animate the sign-up flow
|
||||
/impeccable animate the sign-up flow
|
||||
```
|
||||
|
||||
Typical additions:
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Five-dimension technical quality check with P0 to P3 severity."
|
||||
|
||||
## When to use it
|
||||
|
||||
`/audit` is the technical counterpart to `/critique`. Where `/critique` asks "does this feel right", `/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.
|
||||
`/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".
|
||||
|
||||
@@ -20,12 +20,12 @@ The skill scans your code across five dimensions:
|
||||
|
||||
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 `/polish`, `/harden`, or `/optimize` depending on the category.
|
||||
Audit does not fix anything. It documents. Route the findings to `/impeccable polish`, `/impeccable harden`, or `/impeccable optimize` depending on the category.
|
||||
|
||||
## Try it
|
||||
|
||||
```
|
||||
/audit the checkout flow
|
||||
/impeccable audit the checkout flow
|
||||
```
|
||||
|
||||
Expected output:
|
||||
@@ -41,10 +41,10 @@ Performance: 3/4 (good)
|
||||
...
|
||||
```
|
||||
|
||||
Hand the P0s to `/harden`, the theming and typography P1s to `/typeset` and `/polish`, the rest to `/polish`.
|
||||
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 `/critique`.** Audit is implementation quality. Critique is design quality. Run both for a full picture.
|
||||
- **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.
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Push safe designs toward impact without sliding into chaos."
|
||||
|
||||
## When to use it
|
||||
|
||||
Reach for `/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.
|
||||
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.
|
||||
|
||||
@@ -22,7 +22,7 @@ The skill does not add more. It amplifies what is already there. If the design h
|
||||
## Try it
|
||||
|
||||
```
|
||||
/bolder the landing page hero
|
||||
/impeccable bolder the landing page hero
|
||||
```
|
||||
|
||||
Expected changes:
|
||||
@@ -35,6 +35,6 @@ Expected changes:
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Running it on the wrong page.** Product dashboards, settings, and forms should not be bold. They should be legible. Use `/layout` or `/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 `/quieter`.
|
||||
- **Pairing it with `/delight` in the same pass.** Delight works best against a stable visual baseline. Bold first, stabilize, then delight.
|
||||
- **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.
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Rewrite confusing UX copy so interfaces explain themselves."
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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.
|
||||
`/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".
|
||||
|
||||
@@ -24,7 +24,7 @@ The skill uses the audience and mental state from `.impeccable.md` to tune voice
|
||||
## Try it
|
||||
|
||||
```
|
||||
/clarify the billing form
|
||||
/impeccable clarify the billing form
|
||||
```
|
||||
|
||||
Before and after, typical:
|
||||
@@ -37,6 +37,6 @@ Before and after, typical:
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Writing cleverer, not clearer.** Clarify is not for voice upgrades. If the copy is already clear, do not reach for this skill. Use `/delight` instead when you want personality.
|
||||
- **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 `.impeccable.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.
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Add strategic color to monochrome interfaces without going garish."
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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).
|
||||
`/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
|
||||
|
||||
@@ -20,7 +20,7 @@ Importantly, it uses OKLCH rather than HSL so that equal lightness steps look eq
|
||||
## Try it
|
||||
|
||||
```
|
||||
/colorize the dashboard
|
||||
/impeccable colorize the dashboard
|
||||
```
|
||||
|
||||
Expected diff:
|
||||
@@ -34,5 +34,5 @@ Expected diff:
|
||||
## Pitfalls
|
||||
|
||||
- **Running it without a brand hue.** Colorize needs a starting point. If `.impeccable.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 `/quieter` first, then colorize can rebuild.
|
||||
- **Using it on already-colorful interfaces.** That is a `/quieter` job. Colorize adds, it does not subtract.
|
||||
- **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.
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
tagline: "Shape the design, then build it, all in one flow."
|
||||
---
|
||||
|
||||
## When to use it
|
||||
|
||||
`/impeccable craft` is the end-to-end build command. Give it a feature description and it runs the whole pipeline: structured discovery, reference loading, implementation, visual iteration. Use it when you are starting a new feature from zero and want the whole workflow in one invocation.
|
||||
|
||||
Reach for it when:
|
||||
|
||||
- **You are building a new feature and want the full flow.** You do not want to manage the steps yourself.
|
||||
- **You know what you are building but not how it should look.** The discovery phase forces the design thinking before implementation locks it in.
|
||||
- **You want visual iteration by default.** `craft` checks the result in a browser and refines until the polish is high, instead of shipping the first working version.
|
||||
|
||||
If you only want the thinking without the code, use `/impeccable shape` standalone. If you already have a clear vision and just want to build, call `/impeccable` directly with your feature description. `craft` sits in between: structured, complete, opinionated.
|
||||
|
||||
## How it works
|
||||
|
||||
`craft` runs four phases in order:
|
||||
|
||||
1. **Shape the design.** Runs `/impeccable shape` internally: a short discovery conversation about purpose, users, content, constraints, and goals. The output is a design brief you can read and push back on.
|
||||
2. **Load references.** Based on the brief, pulls in the right reference files (spatial, typography, motion, color, interaction, responsive, UX writing) so the model has the relevant principles loaded before it starts coding.
|
||||
3. **Build.** Implements the feature in a deliberate order: structure first, then spacing and hierarchy, then type and color, then states, then motion, then responsive. Every decision traces back to the brief.
|
||||
4. **Visual iteration.** Opens the result in a browser, checks it against the brief and the anti-pattern catalog, and refines until it matches the intent. This step is critical. The first working version is never the shipped version.
|
||||
|
||||
The discovery phase is non-skippable and that is the point. Most AI-generated UIs fail because nobody asked what the user was trying to accomplish before the model started writing JSX. `craft` inverts that.
|
||||
|
||||
## Try it
|
||||
|
||||
```
|
||||
/impeccable craft a pricing page for a developer tool
|
||||
```
|
||||
|
||||
Expect a 5 to 10 question discovery interview first. Questions about your audience, the product's personality, the emotional tone you want, anti-references, and constraints. Then a design brief. Then implementation, with the browser checked at each stage. Expect multiple iteration rounds in the visual polish phase.
|
||||
|
||||
The whole run is longer than a typical command because it includes the thinking, the building, and the refining. That is the trade: more upfront structure, less cleanup afterwards.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Using it for small changes.** `craft` is for new features, not touch-ups. For existing code, reach for `/impeccable polish`, `/impeccable critique`, or a specific refinement command instead.
|
||||
- **Rushing the discovery phase.** The interview feels slow compared to "just start coding". It is not. Answering the questions carefully produces a sharper brief, which produces a sharper build, which produces fewer rewrites.
|
||||
- **Skipping the visual iteration.** The phase exists for a reason. The gap between "technically works" and "feels right" is closed with visual polish, not code review. Let it run.
|
||||
@@ -4,13 +4,13 @@ tagline: "A design review with scoring, persona tests, and automated detection."
|
||||
|
||||
## When to use it
|
||||
|
||||
Reach for `/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.
|
||||
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
|
||||
|
||||
`/critique` runs two independent assessments in parallel so they do not bias each other.
|
||||
`/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.
|
||||
|
||||
@@ -23,7 +23,7 @@ The two reports merge into one prioritized list: what is working, the three to f
|
||||
Point it at a page:
|
||||
|
||||
```
|
||||
/critique the homepage hero
|
||||
/impeccable critique the homepage hero
|
||||
```
|
||||
|
||||
You get back a scored report. Typical shape:
|
||||
@@ -34,7 +34,7 @@ You get back a scored report. Typical shape:
|
||||
- **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 `/polish` or `/distill` to act on the fixes.
|
||||
From there, pair with `/impeccable polish` or `/impeccable distill` to act on the fixes.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Small moments of personality that turn functional into memorable."
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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.
|
||||
`/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.
|
||||
|
||||
@@ -25,7 +25,7 @@ The rule is: every delight moment must still work perfectly if you delete the de
|
||||
## Try it
|
||||
|
||||
```
|
||||
/delight the first-run experience
|
||||
/impeccable delight the first-run experience
|
||||
```
|
||||
|
||||
Expected additions:
|
||||
|
||||
@@ -4,9 +4,9 @@ tagline: "Ruthless subtraction. Strip designs to their essence."
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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.
|
||||
`/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 `/critique` flags "cognitive load" or "visual noise", or any time a page has grown by accretion and no one has done the editing.
|
||||
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
|
||||
|
||||
@@ -22,7 +22,7 @@ The principle: simplicity is not about fewer features. It is about fewer obstacl
|
||||
## Try it
|
||||
|
||||
```
|
||||
/distill this dashboard
|
||||
/impeccable distill this dashboard
|
||||
```
|
||||
|
||||
Before: four card styles, three button variants, two header treatments, a sidebar with 14 items grouped into 5 sections.
|
||||
@@ -41,4 +41,4 @@ Fewer things. Each one clearer.
|
||||
|
||||
- **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 `/layout` when the problem is layout, not quantity.
|
||||
- **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.
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Pull reusable components, tokens, and patterns into the design system.
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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.
|
||||
`/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.
|
||||
|
||||
@@ -23,7 +23,7 @@ The skill is cautious. It only extracts things used three or more times, with th
|
||||
## Try it
|
||||
|
||||
```
|
||||
/extract the button styles
|
||||
/impeccable extract the button styles
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Make interfaces production-ready. Edge cases, onboarding, i18n, error
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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, empty lists, 500 errors, offline modes, right-to-left text. Designs that only work with perfect data are not production-ready.
|
||||
`/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, empty lists, 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".
|
||||
|
||||
@@ -25,7 +25,7 @@ For each dimension it identifies the failure mode, then applies the concrete fix
|
||||
Start with one page and one dimension:
|
||||
|
||||
```
|
||||
/harden the user profile page for long names
|
||||
/impeccable harden the user profile page for long names
|
||||
```
|
||||
|
||||
Expected output:
|
||||
@@ -40,6 +40,6 @@ Run it per-page, not all at once. The first run is the biggest; subsequent runs
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Waiting for a bug report.** Harden is preventative. If you find yourself fixing the same class of bug twice, run `/harden` across the feature.
|
||||
- **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.
|
||||
|
||||
@@ -1,51 +1,39 @@
|
||||
---
|
||||
tagline: "The design intelligence behind every other skill."
|
||||
tagline: "The design intelligence behind every command."
|
||||
---
|
||||
|
||||
## When to use it
|
||||
|
||||
`/impeccable` is the foundation. It teaches your AI harness how to design, period. Every other command in this pack leans on it for design principles, anti-patterns, typography, color, and layout guidance.
|
||||
`/impeccable` is the home command. Call it directly when you want freeform design work with the full guidebook loaded, without having to pick a specialized command. It is the fallback you reach for when none of the 20 specialists (`audit`, `polish`, `critique`, and the rest) map cleanly onto what you're trying to do.
|
||||
|
||||
Call `/impeccable` directly when you want freeform design with the full guidebook loaded. Or use one of the two sub-modes:
|
||||
Reach for `/impeccable` directly when:
|
||||
|
||||
### /impeccable craft {#craft}
|
||||
- **You're 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 can't own that.
|
||||
- **You want the full design intelligence without constraints.** Every reference file loaded, every anti-pattern checked, no pre-set workflow.
|
||||
|
||||
The full shape-then-build flow. It starts by running `/shape` internally (a structured discovery interview about purpose, audience, and goals), then moves into implementation with visual iteration, checking the result in the browser until the polish is high. Best for brand-new features where you want to think before you build, without managing the steps yourself.
|
||||
|
||||
### /impeccable teach {#teach}
|
||||
|
||||
One-time project setup. Runs a short discovery interview about your brand, audience, and aesthetic direction, then writes a `.impeccable.md` file that every future skill call reads automatically. Run this once per project before doing any design work.
|
||||
|
||||
### /impeccable extract {#extract}
|
||||
|
||||
Pull reusable components, design tokens, and patterns out of your code and into the design system. Finds repeated UI patterns (buttons in 12 places, three card variants, scattered hex colors), extracts them into shared primitives, and migrates all callers. Best used after a product has shipped enough features to reveal the patterns -- premature extraction creates abstractions that do not match reality.
|
||||
For more structured flows, reach for the specialized commands in the sidebar. `/impeccable craft` runs the full shape-then-build pipeline, `/impeccable shape` produces a design brief before any code is written, and the evaluation and refinement commands (`audit`, `critique`, `polish`, `typeset`, etc.) each own a specific slice of the work.
|
||||
|
||||
## How it works
|
||||
|
||||
Most AI-generated UIs fail the same way: generic fonts, purple gradients, card grids on card grids, glassmorphism everywhere. `/impeccable` gives your AI a strong point of view. It loads an opinionated design handbook plus a long list of anti-patterns, then pushes the model to commit to a specific aesthetic direction before writing a single line of code.
|
||||
|
||||
The skill has a **Context Gathering Protocol** built in. It will not design anything until it knows who uses the product, what they're trying to do, and how the interface should feel. If no context exists yet, it asks you to run `/impeccable teach` first. This is deliberate: design without context produces slop, and slop is the whole problem this pack exists to solve.
|
||||
The skill has a **Context Gathering Protocol** built in. It will not design anything until it knows who uses the product, what they're trying to do, and how the interface should feel. On first use in a project, it runs the `teach` flow automatically: a short interview about your brand, audience, and aesthetic direction, saved to `.impeccable.md` so every future command reads it without asking again.
|
||||
|
||||
## Try it
|
||||
|
||||
From a clean project, run once:
|
||||
|
||||
```
|
||||
/impeccable teach
|
||||
/impeccable redo this hero section
|
||||
```
|
||||
|
||||
Answer the discovery questions. The skill writes a `.impeccable.md` file with your brand, audience, and aesthetic direction. Every future skill call reads it automatically.
|
||||
|
||||
Then build something:
|
||||
|
||||
```
|
||||
/impeccable build me a pricing page for a developer tool
|
||||
```
|
||||
|
||||
You should get a page that commits to one clear aesthetic direction, uses non-default fonts, avoids the AI color palette, and has a real point of view.
|
||||
Both prompts are vague on purpose. `/impeccable` will pick a strong aesthetic direction, commit to non-default fonts, avoid the AI color palette, and make the kind of specific choices that a designer would make. No command name to pick first, no step-by-step workflow to follow.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Skipping `/impeccable teach`.** Without a `.impeccable.md` file, the skill has to ask you context questions mid-flight. Faster to set it up once.
|
||||
- **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 that says otherwise), 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.** For that, reach for `/polish`, `/distill`, or `/critique` instead. `/impeccable` is for creation.
|
||||
- **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 `teach` has had a chance to save context.** On a fresh project it will interview you mid-flight, which is fine but slower. Running `/impeccable teach` explicitly as your very first command is a tiny bit smoother.
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Fix layout, spacing, and visual rhythm."
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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.
|
||||
`/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".
|
||||
|
||||
@@ -23,7 +23,7 @@ Fixes usually involve rebuilding the spacing scale, introducing asymmetry, colla
|
||||
## Try it
|
||||
|
||||
```
|
||||
/layout the settings page
|
||||
/impeccable layout the settings page
|
||||
```
|
||||
|
||||
Typical changes:
|
||||
@@ -36,6 +36,6 @@ Typical changes:
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Confusing arrange with distill.** If the problem is too many things, run `/distill` first. Layout is for arranging what is already the right set.
|
||||
- **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.
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Diagnose and fix UI performance from LCP to bundle size."
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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.
|
||||
`/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.
|
||||
|
||||
@@ -23,7 +23,7 @@ The skill measures before and after. Every fix gets quantified. If a change does
|
||||
## Try it
|
||||
|
||||
```
|
||||
/optimize the homepage
|
||||
/impeccable optimize the homepage
|
||||
```
|
||||
|
||||
Expected shape:
|
||||
@@ -51,6 +51,6 @@ Bundle: 340KB → 180KB
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Optimizing before measuring.** Without baseline metrics, you cannot tell what helped. Run `/optimize` with specific Web Vitals numbers, not vibes.
|
||||
- **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.
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "Push an interface past conventional limits. Shaders, physics, 60fps, c
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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.
|
||||
`/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.
|
||||
|
||||
@@ -17,7 +17,7 @@ Overdrive output is announced with `──── ⚡ OVERDRIVE ────` so
|
||||
## Try it
|
||||
|
||||
```
|
||||
/overdrive the landing hero
|
||||
/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.
|
||||
|
||||
@@ -4,7 +4,7 @@ tagline: "The meticulous final pass between good and great."
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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.
|
||||
`/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.
|
||||
|
||||
@@ -24,7 +24,7 @@ The skill is explicit about one thing: polish is the last step, not the first. I
|
||||
## Try it
|
||||
|
||||
```
|
||||
/polish the pricing page
|
||||
/impeccable polish the pricing page
|
||||
```
|
||||
|
||||
A healthy run looks like:
|
||||
@@ -41,6 +41,6 @@ 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 `/polish` on finished features only.
|
||||
- **Treating polish as redesign.** Polish refines what exists. If you find yourself rearchitecting a layout, you needed `/critique` or `/layout` instead.
|
||||
- **Running `/polish` without `/audit` first.** Polish catches feel-based issues. Audit catches measurable ones. Use both.
|
||||
- **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.
|
||||
|
||||
@@ -4,9 +4,9 @@ tagline: "Tone down designs that are shouting without losing their intent."
|
||||
|
||||
## When to use it
|
||||
|
||||
`/quieter` is the counterweight to `/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.
|
||||
`/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 `/bolder` goes a little too far.
|
||||
Also useful after `/impeccable bolder` goes a little too far.
|
||||
|
||||
## How it works
|
||||
|
||||
@@ -22,7 +22,7 @@ The skill preserves the design's intent. If the original had a point of view, th
|
||||
## Try it
|
||||
|
||||
```
|
||||
/quieter the pricing page
|
||||
/impeccable quieter the pricing page
|
||||
```
|
||||
|
||||
Typical diff:
|
||||
@@ -37,4 +37,4 @@ Typical diff:
|
||||
|
||||
- **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 `/distill` first.
|
||||
- **Running it in response to a critique that says "too busy".** Busy usually means too many things, not too loud. Try `/impeccable distill` first.
|
||||
|
||||
@@ -4,13 +4,13 @@ tagline: "Think before you build. Produce a design brief through discovery, not
|
||||
|
||||
## When to use it
|
||||
|
||||
`/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.
|
||||
`/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". `/shape` inverts that order.
|
||||
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:
|
||||
|
||||
@@ -21,17 +21,17 @@ The skill runs a structured discovery interview in conversation. It will not wri
|
||||
|
||||
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 full flow -- discovery interview, then straight into building -- use `/impeccable craft` instead. It runs `/shape` internally, then continues into implementation with visual iteration. `/shape` standalone is for when you want just the brief, so you can take it to whatever implementation approach you prefer.
|
||||
Note: if you want the full flow (discovery interview, then straight into building), use `/impeccable craft` instead. It runs `/impeccable shape` internally, then continues into implementation with visual iteration. `/impeccable shape` standalone is for when you want just the brief, so you can take it to whatever implementation approach you prefer.
|
||||
|
||||
## Try it
|
||||
|
||||
```
|
||||
/shape a daily digest email preferences page
|
||||
/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`, `/polish`, or any other skill. Or just use it as a reference while you build by hand.
|
||||
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
|
||||
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
---
|
||||
tagline: "Teach Impeccable who your product is for, once per project."
|
||||
---
|
||||
@@ -4,7 +4,7 @@ tagline: "Fix typography that feels generic, inconsistent, or accidental."
|
||||
|
||||
## When to use it
|
||||
|
||||
Reach for `/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.
|
||||
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".
|
||||
|
||||
@@ -23,7 +23,7 @@ It then fixes what it finds: picks distinctive typefaces, builds a modular scale
|
||||
## Try it
|
||||
|
||||
```
|
||||
/typeset the article layout
|
||||
/impeccable typeset the article layout
|
||||
```
|
||||
|
||||
Expected diff:
|
||||
@@ -38,5 +38,5 @@ Expected diff:
|
||||
## Pitfalls
|
||||
|
||||
- **Asking for a new font without context.** Typeset will pick based on the `.impeccable.md` brand voice. If you have not run `/impeccable teach`, the suggestion will be generic.
|
||||
- **Reaching for typeset when the issue is layout.** If paragraphs are fine but the page feels cramped, you want `/layout`.
|
||||
- **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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Critique with the visual overlay
|
||||
tagline: "Use /critique plus the browser overlay to review a live page with ground truth."
|
||||
tagline: "Use /impeccable critique plus the browser overlay to review a live page with ground truth."
|
||||
order: 2
|
||||
description: "Run a full design critique that combines LLM assessment, the automated detector, and a live browser overlay so you can see exactly which elements trigger which anti-patterns on the page you're looking at."
|
||||
---
|
||||
@@ -17,12 +17,12 @@ Total time: about ten minutes.
|
||||
- A harness with browser automation available (Claude Code with the Chrome extension, or similar).
|
||||
- A page you want to critique, either local (`localhost:3000/pricing`) or deployed.
|
||||
|
||||
## Step 1. Run /critique
|
||||
## Step 1. Run /impeccable critique
|
||||
|
||||
From your harness, run:
|
||||
|
||||
```
|
||||
/critique the pricing page at localhost:3000/pricing
|
||||
/impeccable critique the pricing page at localhost:3000/pricing
|
||||
```
|
||||
|
||||
The skill kicks off two independent assessments in parallel. They run in separate sub-agents so one does not bias the other.
|
||||
@@ -58,14 +58,14 @@ Every outlined element has a floating label naming the rule that fired. Hover an
|
||||
You have three ways to open it:
|
||||
|
||||
1. **[Chrome extension](https://chromewebstore.google.com/detail/impeccable/bdkgmiklpdmaojlpflclinlofgjfpabf)**: one-click activation on any page. Click the Impeccable icon in the toolbar and every anti-pattern gets highlighted instantly.
|
||||
2. **Inside `/critique`**: the skill opens a browser tab labeled `[Human]` with the detector active during the browser portion of the assessment. You do not need to do anything extra.
|
||||
2. **Inside `/impeccable critique`**: the skill opens a browser tab labeled `[Human]` with the detector active during the browser portion of the assessment. You do not need to do anything extra.
|
||||
3. **Standalone CLI**: `npx impeccable live` starts a local server that serves the detector script. You inject it into any page by adding a `<script>` tag.
|
||||
|
||||
For this tutorial, the easiest option is the Chrome extension. Install it, navigate to your pricing page, and click the Impeccable icon. You will see the overlay appear immediately on the live page.
|
||||
|
||||
## Step 3. Merge the two assessments
|
||||
|
||||
Back in your harness, `/critique` has finished and produced a combined report. It looks something like:
|
||||
Back in your harness, `/impeccable critique` has finished and produced a combined report. It looks something like:
|
||||
|
||||
```
|
||||
AI slop verdict: FAIL
|
||||
@@ -110,17 +110,17 @@ The report gives you a priority list. You can work through them one at a time, a
|
||||
|
||||
This feedback loop is the reason the overlay matters. You see fixes land in real time, and you never ship a "fix" that did not actually satisfy the rule.
|
||||
|
||||
## Step 5. Re-run /critique when you are done
|
||||
## Step 5. Re-run when you are done
|
||||
|
||||
After you have worked through the priority list, run `/critique` again. The goal is a clean AI slop verdict and at least a 3.5 average on the heuristics. Cognitive load should be below 2 failures.
|
||||
After you have worked through the priority list, run `/impeccable critique` again. The goal is a clean AI slop verdict and at least a 3.5 average on the heuristics. Cognitive load should be below 2 failures.
|
||||
|
||||
If something still fires, fix it or write a suppression comment explaining why the rule does not apply in your context (the detector respects a small set of opt-out pragmas, but use them sparingly).
|
||||
|
||||
## What to try next
|
||||
|
||||
- `/audit the same page` to catch the implementation issues critique does not cover (accessibility, performance, theming).
|
||||
- `/polish` if the critique report is clean and you want the last-mile refinement pass.
|
||||
- `/distill` if critique flagged "too busy" or "cognitive load". Distill removes what should not be there.
|
||||
- `/impeccable audit the same page` to catch the implementation issues critique does not cover (accessibility, performance, theming).
|
||||
- `/impeccable polish` if the critique report is clean and you want the last-mile refinement pass.
|
||||
- `/impeccable distill` if critique flagged "too busy" or "cognitive load". Distill removes what should not be there.
|
||||
|
||||
## Common issues
|
||||
|
||||
|
||||
@@ -1,19 +1,31 @@
|
||||
---
|
||||
title: Getting started
|
||||
tagline: "From zero to your first /polish pass in five minutes."
|
||||
tagline: "From zero to your first polish pass in five minutes."
|
||||
order: 1
|
||||
description: "Install Impeccable, run /impeccable teach once to establish project context, and run /polish on something that already exists. The fastest path to seeing what Impeccable changes about AI-generated design."
|
||||
description: "Install Impeccable, run /impeccable teach once to establish project context, and run /impeccable polish on something that already exists. The fastest path to seeing what Impeccable changes about AI-generated design."
|
||||
---
|
||||
|
||||
## What you'll build
|
||||
|
||||
You will end this tutorial with Impeccable installed in your project, a `.impeccable.md` file that captures your brand and audience, and one hand-polished page that went through a `/polish` pass. Total time: about five minutes.
|
||||
You will end this tutorial with Impeccable installed in your project, a `.impeccable.md` file that captures your brand and audience, and one hand-polished page that went through a polish pass. Total time: about five minutes.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- An AI coding harness: Claude Code, Cursor, Gemini CLI, Codex CLI, or any of the other supported tools.
|
||||
- A project with at least one HTML or component file you want to improve. A fresh scaffolded landing page works fine.
|
||||
|
||||
## How Impeccable works
|
||||
|
||||
Impeccable installs as a single agent skill called `impeccable`. You access all 20 design commands through it:
|
||||
|
||||
```
|
||||
/impeccable <command> <target>
|
||||
```
|
||||
|
||||
For example: `/impeccable polish the pricing page`, or `/impeccable audit the checkout`. Type `/impeccable` alone to see the full list.
|
||||
|
||||
If you use a command often, pin it with `/impeccable pin <command>` to create a standalone shortcut (e.g., `/impeccable pin audit` gives you `/audit` directly).
|
||||
|
||||
## Step 1. Install
|
||||
|
||||
From the root of your project, run:
|
||||
@@ -22,7 +34,7 @@ From the root of your project, run:
|
||||
npx skills add pbakaus/impeccable
|
||||
```
|
||||
|
||||
This auto-detects your harness and writes the skill files to the right location (e.g., `.claude/skills/`, `.cursor/skills/`). Reload your harness and type `/`. You should see `/impeccable`, `/polish`, `/critique`, and the other commands in the autocomplete.
|
||||
This auto-detects your harness and writes the skill files to the right location (e.g., `.claude/skills/`, `.cursor/skills/`). Reload your harness and type `/`. You should see `/impeccable` in the autocomplete. Type it and the skill's argument hint will show all available commands.
|
||||
|
||||
## Step 2. Teach Impeccable about your project
|
||||
|
||||
@@ -42,7 +54,7 @@ The skill will ask you a handful of questions:
|
||||
- **Any visual references?** Screenshots, sites, design systems you admire.
|
||||
- **Anti-references?** Things the product should explicitly not look like.
|
||||
|
||||
Answer in your own words. The skill writes a `.impeccable.md` file with the answers. Every future skill call reads it automatically.
|
||||
Answer in your own words. The skill writes a `.impeccable.md` file with the answers. Every future command run reads it automatically.
|
||||
|
||||
Open `.impeccable.md` and read what it wrote. Edit anything that does not feel right. The file is yours.
|
||||
|
||||
@@ -51,7 +63,7 @@ Open `.impeccable.md` and read what it wrote. Edit anything that does not feel r
|
||||
Pick a page that already exists. An about page, a settings screen, a pricing table, anything. Run:
|
||||
|
||||
```
|
||||
/polish the pricing page
|
||||
/impeccable polish the pricing page
|
||||
```
|
||||
|
||||
The skill will walk through alignment, spacing, typography, color, interaction states, transitions, and copy. It makes targeted fixes, not a rewrite. Expect a handful of small diffs that together lift the page from "done" to "done well".
|
||||
@@ -71,9 +83,10 @@ Review the diff. If something does not feel right, ask the model to explain the
|
||||
|
||||
## What to try next
|
||||
|
||||
- `/critique the landing page` runs a full design review with scoring, persona tests, and automated detection. It is the best way to find what to fix next.
|
||||
- `/audit the checkout` runs accessibility, performance, theming, responsive, and anti-pattern checks against the implementation. Useful before shipping.
|
||||
- `/impeccable critique the landing page` runs a full design review with scoring, persona tests, and automated detection. It is the best way to find what to fix next.
|
||||
- `/impeccable audit the checkout` runs accessibility, performance, theming, responsive, and anti-pattern checks against the implementation. Useful before shipping.
|
||||
- `/impeccable craft a pricing page for enterprise customers` runs the full shape-then-build flow on a brand new feature.
|
||||
- `/impeccable redo this hero section` works too. Any description after `/impeccable` applies the design principles to the task.
|
||||
|
||||
## Common issues
|
||||
|
||||
|
||||
Reference in New Issue
Block a user