From e952f3151fab1743f8d988f879d74f8c3bca1c09 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Mon, 4 May 2026 14:24:43 -0700 Subject: [PATCH 1/9] refactor(content): merge content/site/ into site/content/ Phase 1 step 1 of the directory restructure. The dual content tree was called out in CLAUDE.md as cleanup; both trees were already in sync except for anti-patterns-catalog.js, which moves to site/data/. - Delete content/site/skills/ and content/site/tutorials/ (duplicates of site/content/, which is what Astro's content collection actually reads). - Move content/site/anti-patterns-catalog.js -> site/data/. - Update scripts/lib/sub-pages-data.js and scripts/build.js to read from site/content/ and site/data/. - Drop content/site/ from validateProse target list (site/content was already there). - Rewrite the "Two content trees" section in CLAUDE.md as a single-tree pointer; update stale dev-server text mentioning the deleted server/index.js. Tests: 186/186 pass. Skills build: clean. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 19 ++- content/site/skills/adapt.md | 40 ------ content/site/skills/animate.md | 42 ------ content/site/skills/audit.md | 99 ------------- content/site/skills/bolder.md | 40 ------ content/site/skills/clarify.md | 42 ------ content/site/skills/colorize.md | 38 ----- content/site/skills/craft.md | 68 --------- content/site/skills/critique.md | 109 --------------- content/site/skills/delight.md | 42 ------ content/site/skills/distill.md | 44 ------ content/site/skills/document.md | 114 --------------- content/site/skills/extract.md | 64 --------- content/site/skills/harden.md | 44 ------ content/site/skills/impeccable.md | 74 ---------- content/site/skills/layout.md | 41 ------ content/site/skills/live.md | 86 ------------ content/site/skills/onboard.md | 40 ------ content/site/skills/optimize.md | 56 -------- content/site/skills/overdrive.md | 30 ---- content/site/skills/polish.md | 46 ------- content/site/skills/quieter.md | 40 ------ content/site/skills/shape.md | 73 ---------- content/site/skills/teach.md | 70 ---------- content/site/skills/typeset.md | 42 ------ content/site/tutorials/brand-vs-product.md | 130 ------------------ .../site/tutorials/critique-with-overlay.md | 129 ----------------- content/site/tutorials/getting-started.md | 106 -------------- content/site/tutorials/iterate-live.md | 123 ----------------- scripts/build.js | 5 +- scripts/lib/sub-pages-data.js | 12 +- .../data}/anti-patterns-catalog.js | 0 32 files changed, 17 insertions(+), 1891 deletions(-) delete mode 100644 content/site/skills/adapt.md delete mode 100644 content/site/skills/animate.md delete mode 100644 content/site/skills/audit.md delete mode 100644 content/site/skills/bolder.md delete mode 100644 content/site/skills/clarify.md delete mode 100644 content/site/skills/colorize.md delete mode 100644 content/site/skills/craft.md delete mode 100644 content/site/skills/critique.md delete mode 100644 content/site/skills/delight.md delete mode 100644 content/site/skills/distill.md delete mode 100644 content/site/skills/document.md delete mode 100644 content/site/skills/extract.md delete mode 100644 content/site/skills/harden.md delete mode 100644 content/site/skills/impeccable.md delete mode 100644 content/site/skills/layout.md delete mode 100644 content/site/skills/live.md delete mode 100644 content/site/skills/onboard.md delete mode 100644 content/site/skills/optimize.md delete mode 100644 content/site/skills/overdrive.md delete mode 100644 content/site/skills/polish.md delete mode 100644 content/site/skills/quieter.md delete mode 100644 content/site/skills/shape.md delete mode 100644 content/site/skills/teach.md delete mode 100644 content/site/skills/typeset.md delete mode 100644 content/site/tutorials/brand-vs-product.md delete mode 100644 content/site/tutorials/critique-with-overlay.md delete mode 100644 content/site/tutorials/getting-started.md delete mode 100644 content/site/tutorials/iterate-live.md rename {content/site => site/data}/anti-patterns-catalog.js (100%) diff --git a/CLAUDE.md b/CLAUDE.md index f686a6d2..e3583210 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -57,17 +57,16 @@ Editorial brief is at `STYLE.md` (root). Read it before editing the homepage, su The build's `validateProse` step (in `scripts/build.js`) enforces a denylist: em dashes (`—` and HTML entities), the `--` em-dash substitute, `load-bearing`, `highest-leverage`, `biggest unlock`, `seamless`, `robust`, `delve`, `elevate`, `empower`, `underscore`, `pivotal`, `tapestry`, `data-driven`, `reflex defaults`, `collapses into monoculture`, `in today's`, `gone are the days`, `whether you're`, `let's dive in`, `in summary`, `in conclusion`, `moreover`, `furthermore`. Each rule prints a rationale and a suggested replacement when it fires. **Do not silently work around the regex.** If a banned word has earned a real meaning here, raise it as a STYLE.md amendment. -The validator scans `content/site/`, `site/pages/`, `site/content/`, `site/components/`, `site/layouts/`, `README.md`, `README.npm.md`. It deliberately skips `source/skills/impeccable/` because LLM-facing reference instructions sometimes need technical phrasings the marketing copy can't. +The validator scans `site/pages/`, `site/content/`, `site/components/`, `site/layouts/`, `README.md`, `README.npm.md`. It deliberately skips `source/skills/impeccable/` because LLM-facing reference instructions sometimes need technical phrasings the marketing copy can't. The deeper structural issues (negation pivot, triadic auto-pilot, uniform paragraph rhythm, hollow confidence) require human judgment. STYLE.md lists them. Use them on every editorial pass. -## Two content trees: keep them in sync +## Editorial content lives under `site/content/` -After the Astro migration, editorials and tutorials live in TWO places that are both real: -- `content/site/skills/.md` and `content/site/tutorials/.md` — read by `scripts/build.js` for taglines and as source of truth for downstream tooling. -- `site/content/skills/.md` and `site/content/tutorials/.md` — read by Astro's content collection; this is what actually renders on the site. - -There is no automated sync. **Edit both** when changing any editorial or tutorial body. `diff -rq content/site/ site/content/` should always be clean except for `anti-patterns-catalog.js`. Unifying these is on the cleanup list. +Skill editorials and tutorials are read by `scripts/build.js` (for taglines and downstream tooling) and by Astro's content collection (for what actually renders on the site). One tree, one place to edit: +- `site/content/skills/.md` — optional editorial wrapper with frontmatter `tagline` plus body sections +- `site/content/tutorials/.md` — full tutorial content +- `site/data/anti-patterns-catalog.js` — detection-rule catalog (visual examples, gallery items, layer definitions) ## Development Server @@ -76,7 +75,7 @@ bun run dev # Bun dev server at http://localhost:3000 bun run preview # Build + Cloudflare Pages local preview ``` -The dev server (in `server/index.js`) runs `generateSubPages` at module load, so editing source files in `content/site/skills/`, `source/skills/impeccable/`, or the sub-page generator requires a **server restart** (not just a browser reload) to see the change. CSS hot-reloads fine without a restart. +The dev server runs Astro (`astro dev`). Editing files in `site/content/skills/`, `source/skills/impeccable/`, or `scripts/lib/sub-pages-data.js` requires a **server restart** (not just a browser reload) to see the change. CSS, components, and pages hot-reload fine without a restart. **Legacy URL redirects** live in `server/index.js` and must stay in sync with `scripts/build.js` `_redirects` generation. Current redirects: `/skills` → `/docs`, `/skills/:id` → `/docs/:id`, `/cheatsheet` → `/docs`, `/gallery` → `/visual-mode#try-it-live`. @@ -221,7 +220,7 @@ All commands live under `/impeccable`. To add a new one: 8. Add its relationships (leadsTo / pairs / combinesWith) to `COMMAND_RELATIONSHIPS` in the same file 9. Add the same category entry to `public/js/data.js` `commandCategories` and `commandProcessSteps` (for the homepage carousel) 10. Add symbol + number to `commandSymbols` and `commandNumbers` in `public/js/components/framework-viz.js` (periodic table) -11. Optional: write an editorial wrapper at `content/site/skills/.md` with a short `tagline` and expanded body (When to use it / How it works / Try it / Pitfalls) +11. Optional: write an editorial wrapper at `site/content/skills/.md` with a short `tagline` and expanded body (When to use it / How it works / Try it / Pitfalls) The build system counts commands from the router table automatically. Update the command count in **all** of these locations when the total changes: @@ -237,7 +236,7 @@ The build validator (`generateCounts` in `scripts/build.js`) checks these files ## Adding editorial content for existing commands -Editorial files live at `content/site/skills/.md` and have a `tagline` frontmatter plus a body with the standard four sections: +Editorial files live at `site/content/skills/.md` and have a `tagline` frontmatter plus a body with the standard four sections: - **When to use it** — the specific scenarios this command owns - **How it works** — the internal process, phases, or approach diff --git a/content/site/skills/adapt.md b/content/site/skills/adapt.md deleted file mode 100644 index a6b4996b..00000000 --- a/content/site/skills/adapt.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -tagline: "Make designs work across screens, devices, and contexts without amputating features." ---- - -## 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. - -## 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. diff --git a/content/site/skills/animate.md b/content/site/skills/animate.md deleted file mode 100644 index 0cea287b..00000000 --- a/content/site/skills/animate.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -tagline: "Purposeful motion that conveys state, not decoration." ---- - -## 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. diff --git a/content/site/skills/audit.md b/content/site/skills/audit.md deleted file mode 100644 index a5d5c3b6..00000000 --- a/content/site/skills/audit.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -tagline: "Five-dimension technical quality check with P0 to P3 severity." ---- - -
-
-
-
-
/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 25 checks the 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. - -## 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. diff --git a/content/site/skills/bolder.md b/content/site/skills/bolder.md deleted file mode 100644 index cfaf5dd4..00000000 --- a/content/site/skills/bolder.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -tagline: "Push safe designs toward impact without sliding into chaos." ---- - -## 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. diff --git a/content/site/skills/clarify.md b/content/site/skills/clarify.md deleted file mode 100644 index 276c6a80..00000000 --- a/content/site/skills/clarify.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -tagline: "Rewrite confusing UX copy so interfaces explain themselves." ---- - -## 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. diff --git a/content/site/skills/colorize.md b/content/site/skills/colorize.md deleted file mode 100644 index 0cfdf57c..00000000 --- a/content/site/skills/colorize.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -tagline: "Add strategic color to monochrome interfaces without going garish." ---- - -## 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. diff --git a/content/site/skills/craft.md b/content/site/skills/craft.md deleted file mode 100644 index cc370768..00000000 --- a/content/site/skills/craft.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -tagline: "Shape the design, then build it, all in one flow." ---- - -
-
-
- 01 - Shape - Discovery interview. Purpose, users, constraints, direction. -
-
- 02 - Load references - Spatial, typography, motion, color, interaction. -
-
- 03 - Build - Structure, hierarchy, type, color, states, motion, responsive. -
-
- 04 - Iterate visually - Check in browser, refine until it matches the brief. -
-
-

Every phase is non-skippable. The discovery step is where most AI output fails: by the time code exists, the thinking is locked in.

-
- -## 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. diff --git a/content/site/skills/critique.md b/content/site/skills/critique.md deleted file mode 100644 index 59c716ab..00000000 --- a/content/site/skills/critique.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -tagline: "A design review with scoring, persona tests, and automated detection." ---- - -
-
-
-
- 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. diff --git a/content/site/skills/delight.md b/content/site/skills/delight.md deleted file mode 100644 index ba982ea1..00000000 --- a/content/site/skills/delight.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -tagline: "Small moments of personality that turn functional into memorable." ---- - -## 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. diff --git a/content/site/skills/distill.md b/content/site/skills/distill.md deleted file mode 100644 index 66de260c..00000000 --- a/content/site/skills/distill.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -tagline: "Ruthless subtraction. Strip designs to their essence." ---- - -## 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. diff --git a/content/site/skills/document.md b/content/site/skills/document.md deleted file mode 100644 index 63d668b4..00000000 --- a/content/site/skills/document.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -tagline: "Generate a spec-compliant DESIGN.md that captures your visual system so every AI agent stays on-brand." ---- - -
-
-
- 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 -
- -
-
-
- 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, DESIGN.json ships as a machine-readable sidecar for the Live Mode design panel.

-
- -## 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/format/), six sections in a fixed order, interoperable with every other DESIGN.md-aware tool. - -Reach for it when: - -- **You just ran `/impeccable teach`** and `PRODUCT.md` now exists. Document is the matching visual-side file. -- **A command nudged you toward it.** Live, craft, and polish 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. - -For projects with no code yet (fresh `teach` run, nothing built), there is a seed mode: `/impeccable document --seed` asks five quick strategic questions (color strategy, type direction, motion energy, references, anti-references) and writes a scaffold. Re-run in scan mode once there is code. - -## How it works - -The scan pass finds design assets 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 live rendered output if a browser is available. It auto-extracts everything it can, then asks one grouped question for the parts that need creative input: the **Creative North Star** (a single named metaphor for the whole system, like "The Editorial Sanctuary"), descriptive color names, the elevation philosophy, and the component character. - -Output is a DESIGN.md with exactly six sections: Overview, Colors, Typography, Elevation, Components, Do's and Don'ts. Headers are fixed character-for-character so the file is parseable by other tools. Alongside it, `DESIGN.json` is written as a machine-readable sidecar. That sidecar is what the live-mode design panel uses to render *this project's* actual button, input, nav, and card tiles instead of a generic approximation. - -Every other command reads DESIGN.md on invocation. Variants, polishes, audits, and new features inherit the visual system without being told. - -## 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 `` 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. diff --git a/content/site/skills/extract.md b/content/site/skills/extract.md deleted file mode 100644 index 0fb4d97d..00000000 --- a/content/site/skills/extract.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -tagline: "Pull reusable components, tokens, and patterns into the design system." ---- - -
-
-
- 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 ` - - - - - - -

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 (reach for `/impeccable craft`) or whole-page redesigns (reach for `/impeccable` or a specialized refine command). - -## 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", reach for `/impeccable` or `/impeccable craft` 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 teach` and `/impeccable document` first if the result needs to sound like your product. diff --git a/content/site/skills/onboard.md b/content/site/skills/onboard.md deleted file mode 100644 index dd4e2c9c..00000000 --- a/content/site/skills/onboard.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -tagline: "Design first-run experiences, empty states, and paths to value." ---- - -## 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. diff --git a/content/site/skills/optimize.md b/content/site/skills/optimize.md deleted file mode 100644 index 545d596c..00000000 --- a/content/site/skills/optimize.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -tagline: "Diagnose and fix UI performance from LCP to bundle size." ---- - -## 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. diff --git a/content/site/skills/overdrive.md b/content/site/skills/overdrive.md deleted file mode 100644 index 61a2a26e..00000000 --- a/content/site/skills/overdrive.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -tagline: "Push an interface past conventional limits. Shaders, physics, 60fps, cinematic transitions." ---- - -## 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. diff --git a/content/site/skills/polish.md b/content/site/skills/polish.md deleted file mode 100644 index 9c7a5f0e..00000000 --- a/content/site/skills/polish.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -tagline: "The meticulous final pass between good and great." ---- - -## 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. diff --git a/content/site/skills/quieter.md b/content/site/skills/quieter.md deleted file mode 100644 index e589df5c..00000000 --- a/content/site/skills/quieter.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -tagline: "Tone down designs that are shouting without losing their intent." ---- - -## 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. diff --git a/content/site/skills/shape.md b/content/site/skills/shape.md deleted file mode 100644 index 7f51beed..00000000 --- a/content/site/skills/shape.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -tagline: "Think before you build. Produce a design brief through discovery, not guesswork." ---- - -
-
-
- 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, /impeccable craft, 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 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 - -``` -/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. diff --git a/content/site/skills/teach.md b/content/site/skills/teach.md deleted file mode 100644 index c57da2ec..00000000 --- a/content/site/skills/teach.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -tagline: "Teach Impeccable who your product is for, once per project." ---- - -
-
-
- PRODUCT.md - Loaded on every command -
-
-
- Register - Product. Design serves the task. -
-
- Users - SREs on call, reading fast, often in the dark. -
-
- Brand voice - Calm, clinical, no hype. -
-
- Anti-references - Purple gradients. Glassmorphism. "Boost your productivity." -
-
-
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 teach` once at the start of a project. It is the onramp. Without it, every other command will produce design that is technically competent but generically toned: stock 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 `teach` and the updated context flows through every command. -- **Another command said "no design context found"** and stopped. That is the signal: run teach, then resume. - -## How it works - -Teach writes two complementary files at the project root: - -- **`PRODUCT.md`** is the strategic file. Register (brand or product), target users, product purpose, brand personality, anti-references, design principles, 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 teach invokes at the end. - -The flow scans the codebase first (README, package.json, components, tokens, brand assets) and forms a **register hypothesis**: brand (landing, marketing, portfolio, where design IS the product) or product (app UI, dashboards, tools, where design SERVES the product). Register is the first question, because it shapes every downstream answer: typography defaults, motion energy, color strategy, the reference set commands like `/impeccable typeset` pull from. After register, teach asks only what it could not infer: users, personality in three real words, references and anti-references, accessibility requirements. - -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. - -## Try it - -``` -/impeccable teach -``` - -Expect a 5 to 8 minute interview. The first question is usually about register; the rest are short. Teach will quote back what it inferred from your code ("from the routes, this looks like a product surface, match?") so you are confirming, not starting from scratch. - -At the end, teach 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 teach first is faster, not slower. -- **Giving generic answers.** "Modern and clean" is not useful. "Warm, mechanical, opinionated" is. Be specific. Be willing to disagree with safe defaults. -- **Treating PRODUCT.md as immutable.** The file is yours. If teach put something in there that is not quite right, edit it. Every command reads the current file. -- **Listing only adjectives for references.** Brands, products, printed objects: named, not described. "Klim Type Foundry specimen pages", not "technical and clean". Anti-references should be equally specific. diff --git a/content/site/skills/typeset.md b/content/site/skills/typeset.md deleted file mode 100644 index 8c31a086..00000000 --- a/content/site/skills/typeset.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -tagline: "Fix typography that feels generic, inconsistent, or accidental." ---- - -## 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 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 `/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. diff --git a/content/site/tutorials/brand-vs-product.md b/content/site/tutorials/brand-vs-product.md deleted file mode 100644 index 6aa7c5b1..00000000 --- a/content/site/tutorials/brand-vs-product.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Brand vs product, pick a register -tagline: "Two worlds, two sets of defaults. Pick the right one and every command downstream benefits." -order: 3 -description: "Impeccable treats brand work (landing pages, campaigns, portfolios) and product work (app UI, dashboards, tools) as different worlds with different defaults. Learn how to pick a register and how it shapes every command that reads it." ---- - -## See the divergence - -Same element, one register each. A newsletter signup, twice. - -
-
-
-
- Brand - Editorial-magazine -
-
- No. 04  ·  Dispatch -

Letters, occasionally.

-

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

- Send me one -
-
- Serif display, italic display weight - Drenched in the primary hue - Monospaced kicker, editorial voice -
-
-
-
- Product - Utility / app shell -
-
- Newsletter -

Subscribe to updates

-

Product changes and release notes, once a month. Unsubscribe at any time.

- Subscribe -
-
- Neutral sans, semibold for hierarchy - Restrained palette, accent only on state - Short, scannable, mobile-readable copy -
-
-
-

The table below lists what's different. This is what it looks like at the pixel.

-
- -## Why register matters - -Every design task belongs to one of two worlds: - -- **Brand** is where design IS the product. Marketing sites, landing pages, portfolios, long-form content, campaign surfaces. Distinctiveness is the bar. Fonts, motion, density, and color all push toward "this looks like nothing else in the category." -- **Product** is where design SERVES the product. App UI, admin, dashboards, tools. Earned familiarity is the bar. Fluent users of Linear, Figma, Notion, Raycast, or Stripe should trust the output on sight. - -If you ask the same AI to design a dashboard and a campaign page without naming which world, you'll get the average of the two. Brand surfaces will feel too careful. Product surfaces will feel too precious. Register is how Impeccable avoids that. - -Impeccable tracks register as a single field in `PRODUCT.md`: - -```markdown -## Register - -product -``` - -That is it: a bare value, `brand` or `product`. Every command that does register-sensitive work (`typeset`, `animate`, `colorize`, `layout`, `bolder`, `quieter`, `delight`) loads a different reference file based on what it finds here. - -## How the two worlds diverge - -This is not an exhaustive list, the full divergence lives in the `brand.md` and `product.md` reference files, but the shape of the difference: - -| Dimension | Brand | Product | -|---|---|---| -| **Type lanes** | Editorial-magazine, luxury, brutalist, consumer-warm, tech-minimal, all available. Swing. | Tighter set: neutral sans + optional mono, sized for dense reading, fluid type reserved for marketing surfaces. | -| **Motion** | Choreographed entrances, scroll-driven sequences, decorative moments earn their place. | Restrained. State changes only. Animation serves feedback, not atmosphere. | -| **Color** | Full palette, Committed, or Drenched are all on the table. | Restrained by default. Accents carry meaning; color is not decoration. | -| **Density** | Whatever the narrative wants. Generous whitespace or packed rule-divided columns both valid. | Comfortable to dense. Every pixel earns its place. | -| **References** | Real-world, from the right lane. *Klim specimen pages* or *Broadsheet masthead*, not "modern SaaS". | Category best-tool. *Linear*, *Figma*, *Notion*, *Raycast*, *Stripe*. | - -The same command, `/impeccable typeset`, pulls from different fonts in the two worlds. The same command, `/impeccable animate`, picks different motion vocabularies. The same command, `/impeccable layout`, assumes different density defaults. You do not re-learn the command: you answer the register question once, and the command adapts. - -## Step 1. Decide or inherit - -If you haven't run `/impeccable teach` yet, run it now. The first question is about register: - -``` -/impeccable teach -``` - -Teach scans your codebase first and forms a hypothesis: routes like `/`, `/pricing`, `/blog`, hero sections, scroll-driven content point toward brand. Routes like `/app`, `/dashboard`, `/settings`, forms and tables point toward product. It leads with the hypothesis rather than starting cold: - -> From the codebase, this looks like a product surface, does that match your intent, or should we treat it differently? - -If the project genuinely spans both (a product with a big marketing landing), teach asks which register describes the **primary** surface. Register is per-project, not per-page, but you can override it per task when needed. - -## Step 2. Verify the register landed - -Open `PRODUCT.md` and look for the `## Register` section. It should carry a bare value, not prose: - -```markdown -## Register - -brand -``` - -If the section is missing (you're on an older `PRODUCT.md` from pre-v3.0), re-run `/impeccable teach`. It will detect the gap and add the field without re-interviewing you on everything else. - -## Step 3. Override per task when you need to - -Most of the time, register is set once and forgotten. But a product project might occasionally need a single brand surface (a launch landing, an investor one-pager) without flipping the whole project. - -You have two options: - -- **Name it in the brief.** "`/impeccable craft a launch landing for v2, brand register for this one page.`" The skill honors the override for that task only. -- **Set a per-surface register.** If the override is lasting, add a short note in `PRODUCT.md` under an explicit section: `## Register overrides: /launch is brand.` Commands that read PRODUCT.md will respect it. - -## What to try next - -- Run a command that is register-sensitive and watch the divergence: `/impeccable typeset the pricing page` on a product project vs. a brand project will pick different type families, different scale ratios, and different pairings. -- Pair with [getting started](/tutorials/getting-started) if you haven't installed Impeccable yet. -- Reach for `/impeccable document` after teach to capture the visual side (colors, components) into DESIGN.md. - -## Common issues - -- **Register keeps slipping the wrong way.** If you set `product` but commands keep producing brand-feeling output, check that `PRODUCT.md` is at the project root and the `## Register` section has a bare value (no prose, no explanation, just the word). Commands can only read what is there. -- **The hypothesis teach formed is wrong.** Disagree in the answer. Teach is asking, not telling. -- **A project is genuinely 50/50.** Pick the primary surface, then use per-task overrides for the minority one. Trying to average the two in PRODUCT.md produces worse output than committing to one. diff --git a/content/site/tutorials/critique-with-overlay.md b/content/site/tutorials/critique-with-overlay.md deleted file mode 100644 index 76e2f119..00000000 --- a/content/site/tutorials/critique-with-overlay.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Critique with the visual overlay -tagline: "Use /impeccable critique plus the browser overlay to review a live page with ground truth." -order: 4 -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." ---- - -## What you'll build - -You will run a complete design critique against a live page in your browser, with every flagged anti-pattern highlighted directly on the element that caused it. No screenshots, no guesswork, no paragraph of findings you have to map back to the code. - -Total time: about ten minutes. - -## Prerequisites - -- Impeccable installed in your project (see [getting started](/tutorials/getting-started) if you have not). -- 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 /impeccable critique - -From your harness, run: - -``` -/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. - -### What the LLM assessment does - -The first assessment reads your source code and, if browser automation is available, opens the live page in a new tab. It walks the full impeccable skill DO/DON'T catalog and scores the page against Nielsen's 10 heuristics, the 8-item cognitive load checklist, and the brand fit from your `PRODUCT.md`. - -It labels the tab it opens with `[LLM]` in the title so you can tell which one is which. - -### What the automated detector does - -The second assessment runs `npx impeccable detect` against the page. This is deterministic: around thirty specific pattern checks that fire or do not fire. Gradient text, purple palettes, side-tab borders, nested cards, line length problems, low contrast, tiny body text, and the rest. The [full catalog](/anti-patterns) lists every rule and which layer (CLI, browser, or LLM-only) catches it. - -You get back a JSON list of every finding with its element selector, the rule that fired, and a short description. - -## Step 2. Open the visual overlay - -Impeccable ships with a visual mode that highlights every detected anti-pattern directly on the page. Here is what it looks like running on a deliberately-bad synthwave landing page: - -
-
- - - - Live detection overlay -
- -
- -Every outlined element has a floating label naming the rule that fired. Hover an outline to see the full finding. This is exactly what you will see on your own page. - -You have two 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 `/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. - -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, `/impeccable critique` has finished and produced a combined report. It looks something like: - -``` -AI slop verdict: FAIL - Detected tells: gradient-text (2), ai-color-palette (1), - nested-cards (1), side-tab (3) - -Heuristic scores (avg 2.8/4): - Visibility of status: 3 (good) - Match between system and real world: 2 (partial) - Consistency and standards: 2 (partial) - ... - -Cognitive load: 3/8 failures (moderate) - Visible options at primary decision: 6 (flag) - Decision points stacked at top: yes (flag) - Progressive disclosure: absent on advanced pricing toggles - -What's working: - - Clear price hierarchy - - Strong headline - -Priority issues: - 1. Hero uses gradient text on the main price - Why: AI tell, reduces contrast, hurts scannability - Fix: solid ink color at one weight heavier - 2. Feature comparison table has 4 nested card levels - Why: visual noise, unclear hierarchy - Fix: flatten to a table with zebra striping - -Questions to answer: - - Is the free tier a real product or a funnel? - - What does a user feel when they land here from an ad vs from search? -``` - -## Step 4. Fix the findings - -The report gives you a priority list. You can work through them one at a time, ask the model to fix them all at once, or anything in between. What matters is using the overlay to verify: - -1. Keep the overlay open in one tab. -2. Make fixes in code (or ask the model to fix everything). -3. Reload. The overlay re-scans and resolved findings disappear. - -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 when you are done - -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 - -- [Iterate on the critique findings with Live Mode](/tutorials/iterate-live). Pick the element critique flagged, drop a comment, get three redirections hot-swapped in place, and write the accepted one back to source. -- `/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 - -- **The overlay shows no findings but critique says there are problems**. The detector catches deterministic patterns. Critique catches judgment calls. They are complementary, not redundant. -- **The LLM assessment and the detector disagree**. That is normal. The LLM is subjective. The detector is deterministic. When they disagree, look at both and make a call. -- **The overlay breaks the page layout**. Rare, but some CSS can interact with the injected overlay styles. Use the [Chrome extension](https://chromewebstore.google.com/detail/impeccable/bdkgmiklpdmaojlpflclinlofgjfpabf) for the most reliable experience, or run `npx impeccable detect` from the CLI and apply findings manually. diff --git a/content/site/tutorials/getting-started.md b/content/site/tutorials/getting-started.md deleted file mode 100644 index 37d1289c..00000000 --- a/content/site/tutorials/getting-started.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Getting started -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 /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 `PRODUCT.md` plus `DESIGN.md` pair that captures your brand, audience, and visual system, and one hand-polished page that went through a polish pass. Total time: about ten 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 23 sub-commands through it: - -``` -/impeccable -``` - -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 ` to create a standalone shortcut (for example, `/impeccable pin audit` gives you `/audit` directly). - -## Step 1. Install - -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` in the autocomplete. Type it and the skill's argument hint will show all available commands. - -## Step 2. Teach Impeccable about your project - -This is the most important step. Design without context produces generic output. The `/impeccable teach` command runs a short discovery interview and writes a `PRODUCT.md` file at the root of your project. - -Run: - -``` -/impeccable teach -``` - -The first question is about **register**: is this a brand surface (marketing site, landing page, portfolio, where design IS the product) or a product surface (app UI, dashboard, tools, where design SERVES the product)? Register shapes every downstream default, from type lanes to motion energy. See [brand vs product](/tutorials/brand-vs-product) for how the two diverge. Teach will form a hypothesis from your codebase and ask you to confirm, rather than starting cold. - -Then a handful of shorter questions: - -- **Who is this product for?** Be specific. Not "users" but "solo founders evaluating a new tool on their phone between meetings". -- **What is the brand voice in three words?** Pick real words. "Warm and mechanical and opinionated" is better than "modern and clean". -- **Any visual references?** Named brands, products, or printed objects, not adjectives. "Klim Type Foundry specimen pages", not "technical and clean". -- **Anti-references?** Things the product should explicitly not look like, equally named. - -Answer in your own words. The skill writes `PRODUCT.md` with the answers. Every future command run reads it automatically. - -Open `PRODUCT.md` and read what it wrote. Edit anything that does not feel right. The file is yours. - -## Step 2.5. Capture the visual system - -At the end of `/impeccable teach`, the skill offers to run `/impeccable document` for you. Say yes. It scans your tokens (CSS custom properties, Tailwind config, CSS-in-JS themes), extracts colors and typography, asks one grouped question for the parts that need creative input (a Creative North Star, descriptive color names), and writes a `DESIGN.md` that follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). - -On a fresh project with no tokens yet, document runs in seed mode: five quick questions about color strategy, type direction, and motion energy, and writes a scaffold you can refresh once there is code. - -`PRODUCT.md` carries strategy (who, what, why). `DESIGN.md` carries visuals (colors, typography, components). Every command reads both before generating. - -## Step 3. Polish something - -Pick a page that already exists. An about page, a settings screen, a pricing table, anything. Run: - -``` -/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". - -A typical polish pass looks like: - -``` -Visual alignment: fixed 3 off-grid elements -Typography: tightened h1 kerning, fixed widow on feature list -Color: replaced one hardcoded hex with --color-accent token -Interaction: added missing hover state on FAQ items -Motion: softened modal entrance to 220ms ease-out-quart -Copy: removed stray 'Lorem' placeholder -``` - -Review the diff. If something does not feel right, ask the model to explain the change. If it still does not feel right, revert it. Impeccable is opinionated but not infallible. - -## What to try next - -- [Iterate visually with Live Mode](/tutorials/iterate-live) opens a browser picker on your dev server, generates three production-quality variants per element, and writes the accepted one back to source. -- `/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. -- **Pin your favorites.** If you reach for one command constantly, `/impeccable pin audit` makes `/audit` work as a standalone shortcut without reversing the consolidation. -- `/impeccable redo this hero section` works too. Any description after `/impeccable` applies the design principles to the task. - -## Common issues - -- **The skill says "no design context found"**. You skipped step 2. Run `/impeccable teach` first. -- **Commands do not appear in the harness**. Reload the harness after installing. If they still do not appear, check that the installer wrote files into the expected location (`.claude/skills/`, `.cursor/skills/`, etc.) and that your harness is picking up that directory. -- **The polish pass rewrote something you liked**. Say so. Revert the change, tell the model which specific edit to undo, and continue from there. diff --git a/content/site/tutorials/iterate-live.md b/content/site/tutorials/iterate-live.md deleted file mode 100644 index b510d119..00000000 --- a/content/site/tutorials/iterate-live.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Iterate on UI with Live Mode -tagline: "Pick an element, generate three variants, accept one. Canvas-like iteration without leaving your code." -order: 2 -description: "Use /impeccable live to visually iterate on a real element in your dev server: pick, annotate, generate three variants, accept the one you want, and have it written back to source." ---- - -## What you'll build - -You will use `/impeccable live` on your dev server to iterate on a single piece of UI (a hero, a card, a section) and end with one of three AI-generated variants written back to source as real code. You'll see the canvas-style picking, annotation, and three-up cycling flow. - -Total time: about ten minutes. Most of that is picking what to iterate on. - -## Prerequisites - -- Impeccable installed (see [getting started](/tutorials/getting-started) if you have not). Run `/impeccable teach` first if you haven't yet: variants lean on `PRODUCT.md` and `DESIGN.md` for brand fit. -- A running dev server with HMR (Vite, Next.js, SvelteKit, Astro, Nuxt, Bun) OR a static HTML file open in a browser. -- A page with at least one piece of UI you'd like to iterate on. A newsletter card, a hero, a pricing tier, something small enough to hold in your head. - -## Step 1. Start live mode - -From your harness, run: - -``` -/impeccable live -``` - -The skill starts a small local helper server on port 8400 and injects a `