mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-20 10:06:54 +03:00
feat(site): v3.0 changelog expansion, pin FAQ, stale-ref cleanup
- v3.0 changelog now covers 6 items (was 2): Live Mode, PRODUCT.md, DESIGN.md (with Google Stitch spec compliance), brand/product registers, plus the existing consolidation + pin/unpin. - New FAQ entry answering "how do I get /critique back" via pinning. - Added Pin commands back as shortcuts section to /docs/impeccable editorial so it's findable outside the FAQ. - Reduced changelog item font size (0.9375rem) to match length. - Swept user-facing copy: .impeccable.md -> PRODUCT.md, removed three stale npx impeccable live references (the CLI subcommand no longer exists; live is /impeccable live inside the skill). - Historical v1.5.0 changelog entry preserved as-is (period-accurate).
This commit is contained in:
Paul Bakaus
@@ -19,7 +19,7 @@ The skill rewrites text across the surfaces where most UX copy problems live:
|
||||
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 `.impeccable.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.
|
||||
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
|
||||
|
||||
@@ -38,5 +38,5 @@ Before and after, typical:
|
||||
## Pitfalls
|
||||
|
||||
- **Writing cleverer, not clearer.** Clarify is not for voice upgrades. If the copy is already clear, do not reach for this skill. Use `/impeccable delight` instead when you want personality.
|
||||
- **Skipping the audience question.** Clarify needs to know who is reading. If `.impeccable.md` does not specify audience technical level, the rewrites will be generic.
|
||||
- **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.
|
||||
|
||||
@@ -33,6 +33,6 @@ Expected diff:
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Running it without a brand hue.** Colorize needs a starting point. If `.impeccable.md` does not specify one, it will ask. Do not let it pick from the AI color palette defaults.
|
||||
- **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.
|
||||
|
||||
@@ -18,7 +18,7 @@ The skill hunts for delight opportunities in the places most designers skip:
|
||||
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 `.impeccable.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 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.
|
||||
|
||||
@@ -37,6 +37,6 @@ Expected additions:
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Forcing humor.** Not every brand is playful. If the brand voice in `.impeccable.md` is "clinical and precise", delight adds clever restraint, not jokes.
|
||||
- **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.
|
||||
|
||||
@@ -18,7 +18,7 @@ For more structured flows, reach for the specialized commands in the sidebar. `/
|
||||
|
||||
Most AI-generated UIs fail the same way: generic fonts, purple gradients, card grids on card grids, glassmorphism everywhere. `/impeccable` gives your AI a strong point of view. It loads an opinionated design handbook plus a long list of anti-patterns, then pushes the model to commit to a specific aesthetic direction before writing a single line of code.
|
||||
|
||||
The skill has a **Context Gathering Protocol** built in. It will not design anything until it knows who uses the product, what they're trying to do, and how the interface should feel. On first use in a project, it runs the `teach` flow automatically: a short interview about your brand, audience, and aesthetic direction, saved to `.impeccable.md` so every future command reads it without asking again.
|
||||
The skill has a **Context Gathering Protocol** built in. It will not design anything until it knows who uses the product, what they're trying to do, and how the interface should feel. On first use in a project, it runs the `teach` flow automatically: a short interview about your brand, audience, and aesthetic direction, saved to `PRODUCT.md` so every future command reads it without asking again.
|
||||
|
||||
## Try it
|
||||
|
||||
@@ -32,6 +32,25 @@ The skill has a **Context Gathering Protocol** built in. It will not design anyt
|
||||
|
||||
Both prompts are vague on purpose. `/impeccable` will pick a strong aesthetic direction, commit to non-default fonts, avoid the AI color palette, and make the kind of specific choices that a designer would make. No command name to pick first, no step-by-step workflow to follow.
|
||||
|
||||
## Pin commands back as shortcuts
|
||||
|
||||
v3.0 consolidated 18 standalone skills into a single `/impeccable` with sub-commands. If you miss the short form of a specific command, pin it back:
|
||||
|
||||
```
|
||||
/impeccable pin critique
|
||||
```
|
||||
|
||||
From now on, `/critique` invokes `/impeccable critique` directly. It writes a lightweight redirect skill that delegates to the parent, so updates to the skill flow through without re-pinning.
|
||||
|
||||
Useful pins to try:
|
||||
|
||||
- `/impeccable pin polish` for final-pass work
|
||||
- `/impeccable pin audit` for deterministic a11y/perf checks
|
||||
- `/impeccable pin live` for the browser iteration flow
|
||||
- `/impeccable pin critique` for design review
|
||||
|
||||
To remove: `/impeccable unpin critique`. Pins live as directories prefixed with `i-` in your harness skills folder (`.claude/skills/i-critique/`, `.cursor/skills/i-critique/`, etc.), so you can also delete them manually.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Treating it like a style guide.** It is an opinionated design partner, not a linter. The defaults exist to raise the floor, not to overrule your judgment. If you have a real reason to push back (brand guideline, accessibility constraint, user research that says otherwise), push back and explain why. The skill will work with you. What produces worse output is ignoring the opinion without a reason.
|
||||
|
||||
@@ -37,6 +37,6 @@ Expected diff:
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **Asking for a new font without context.** Typeset will pick based on the `.impeccable.md` brand voice. If you have not run `/impeccable teach`, the suggestion will be generic.
|
||||
- **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.
|
||||
|
||||
@@ -29,7 +29,7 @@ The skill kicks off two independent assessments in parallel. They run in separat
|
||||
|
||||
### 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 `.impeccable.md`.
|
||||
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.
|
||||
|
||||
@@ -55,11 +55,10 @@ Impeccable ships with a visual mode that highlights every detected anti-pattern
|
||||
|
||||
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 three ways to open it:
|
||||
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.
|
||||
3. **Standalone CLI**: `npx impeccable live` starts a local server that serves the detector script. You inject it into any page by adding a `<script>` tag.
|
||||
|
||||
For this tutorial, the easiest option is the Chrome extension. Install it, navigate to your pricing page, and click the Impeccable icon. You will see the overlay appear immediately on the live page.
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ description: "Install Impeccable, run /impeccable teach once to establish projec
|
||||
|
||||
## What you'll build
|
||||
|
||||
You will end this tutorial with Impeccable installed in your project, a `.impeccable.md` file that captures your brand and audience, and one hand-polished page that went through a polish pass. Total time: about five minutes.
|
||||
You will end this tutorial with Impeccable installed in your project, a `PRODUCT.md` file that captures your brand and audience, and one hand-polished page that went through a polish pass. Total time: about five minutes.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -38,7 +38,7 @@ This auto-detects your harness and writes the skill files to the right location
|
||||
|
||||
## 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 `.impeccable.md` file at the root of 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:
|
||||
|
||||
@@ -54,9 +54,9 @@ The skill will ask you a handful of questions:
|
||||
- **Any visual references?** Screenshots, sites, design systems you admire.
|
||||
- **Anti-references?** Things the product should explicitly not look like.
|
||||
|
||||
Answer in your own words. The skill writes a `.impeccable.md` file with the answers. Every future command run reads it automatically.
|
||||
Answer in your own words. The skill writes a `PRODUCT.md` file with the answers. Every future command run reads it automatically.
|
||||
|
||||
Open `.impeccable.md` and read what it wrote. Edit anything that does not feel right. The file is yours.
|
||||
Open `PRODUCT.md` and read what it wrote. Edit anything that does not feel right. The file is yours.
|
||||
|
||||
## Step 3. Polish something
|
||||
|
||||
|
||||
@@ -1161,8 +1161,9 @@
|
||||
margin: 0;
|
||||
padding-left: var(--spacing-md);
|
||||
color: var(--color-charcoal);
|
||||
line-height: 1.7;
|
||||
max-width: 70ch;
|
||||
font-size: 0.9375rem;
|
||||
line-height: 1.65;
|
||||
max-width: 72ch;
|
||||
}
|
||||
|
||||
.changelog-items li {
|
||||
|
||||
+22
-6
@@ -311,8 +311,8 @@
|
||||
<p>No LLM needed. Pattern matching catches purple gradients, overused fonts, nested cards, low contrast, and more.</p>
|
||||
</div>
|
||||
<div class="visual-mode-feature">
|
||||
<span class="visual-mode-feature-label">Three ways to use it</span>
|
||||
<p>The <strong>Chrome extension</strong> on any site, embedded in <code>/impeccable critique</code> during an AI design review, or standalone via <code>npx impeccable live</code>.</p>
|
||||
<span class="visual-mode-feature-label">Two ways to use it</span>
|
||||
<p>The <strong>Chrome extension</strong> on any site, or embedded in <code>/impeccable critique</code> during an AI design review.</p>
|
||||
</div>
|
||||
<a href="https://chromewebstore.google.com/detail/impeccable/bdkgmiklpdmaojlpflclinlofgjfpabf" class="detection-callout" target="_blank" rel="noopener">
|
||||
<img src="assets/extension-detection.png" alt="Impeccable Chrome extension panel listing detected anti-patterns" class="detection-callout-image" loading="lazy" width="600" height="508">
|
||||
@@ -516,6 +516,10 @@
|
||||
<span class="changelog-date">April 10, 2026</span>
|
||||
</div>
|
||||
<ul class="changelog-items">
|
||||
<li><strong>Live Mode.</strong> Run <code>/impeccable live</code> and iterate on your UI in the browser: pick any element, drop a comment or stroke, hit Go, get three production-quality variants swapped in via your framework's HMR, accept the one you want and it writes back to source. Works on Vite, Next.js (including monorepos), SvelteKit, Astro, Nuxt. Detects your project's Content Security Policy and offers a one-time, dev-only patch so it runs in strict-CSP apps too.</li>
|
||||
<li><strong>PRODUCT.md, shared design memory for your AI.</strong> A single file at your project root that names the audience, brand personality, anti-references, and register (brand vs product). Every command reads it before generating, so output stops drifting into generic "modern SaaS" territory and starts sounding like your product. Created in one step via <code>/impeccable teach</code>.</li>
|
||||
<li><strong>DESIGN.md generation, spec-compliant and interoperable.</strong> <code>/impeccable document</code> scans your tokens, components, and rendered output and writes a DESIGN.md that follows the <a href="https://stitch.withgoogle.com/docs/design-md/format/" target="_blank" rel="noopener">Google Stitch DESIGN.md format</a>. Colors, typography, elevation, components, do's and don'ts, in the exact six sections other DESIGN.md-aware tools expect. Your visual system travels with you.</li>
|
||||
<li><strong>Brand and product registers.</strong> Design work splits cleanly into two worlds: brand (marketing sites, landing pages, portfolios, where design IS the product) and product (app UI, dashboards, tools, where design SERVES the product). Register-aware commands (<code>typeset</code>, <code>animate</code>, <code>bolder</code>, <code>quieter</code>, <code>colorize</code>, <code>layout</code>, <code>delight</code>) each adjust their vocabulary to match, so brand work isn't critiqued for breaking product-UI conventions and vice versa.</li>
|
||||
<li><strong>18 skills became 1 skill with 23 commands.</strong> Every command now lives under <code>/impeccable</code>: <code>/impeccable audit</code>, <code>/impeccable polish</code>, <code>/impeccable critique</code>, and the rest. One entry in your <code>/</code> menu instead of 18, a shared design vocabulary between you and your AI, and far less namespace pollution as the plugin ecosystem grows. The autocomplete shows the full list the moment you type <code>/impeccable</code>.</li>
|
||||
<li><strong>Pin your favorites back as shortcuts.</strong> Run <code>/impeccable pin audit</code> and <code>/audit</code> becomes a standalone command again, without reversing the consolidation. Under the hood it writes a lightweight redirect skill that delegates to <code>/impeccable audit</code>, so updates to the parent skill flow through automatically. <code>/impeccable unpin audit</code> removes it.</li>
|
||||
</ul>
|
||||
@@ -672,7 +676,22 @@
|
||||
<li><strong>Claude Code plugin:</strong> Open <code>/plugin</code>, go to the Discover tab.</li>
|
||||
<li><strong>Manual ZIP:</strong> Download from above and extract to the project root.</li>
|
||||
</ul>
|
||||
<p>Your <code>.impeccable.md</code> context file is never overwritten.</p>
|
||||
<p>Your <code>PRODUCT.md</code> and <code>DESIGN.md</code> context files are never overwritten.</p>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
<details class="faq-item">
|
||||
<summary class="faq-question">I used to type <code>/critique</code> directly. How do I get that back?</summary>
|
||||
<div class="faq-answer">
|
||||
<p>Pinning is built in. Run <code>/impeccable pin critique</code> and <code>/critique</code> becomes a standalone shortcut again, without reversing the consolidation.</p>
|
||||
<p>Under the hood it writes a lightweight redirect skill that delegates to <code>/impeccable critique</code>, so updates to the parent skill flow through automatically. It works for every command.</p>
|
||||
<p><strong>Examples:</strong></p>
|
||||
<ul>
|
||||
<li><code>/impeccable pin polish</code> → <code>/polish</code> works again</li>
|
||||
<li><code>/impeccable pin audit</code> → <code>/audit</code> works again</li>
|
||||
<li><code>/impeccable pin live</code> → <code>/live</code> works again</li>
|
||||
</ul>
|
||||
<p>To remove: <code>/impeccable unpin critique</code>. To see your current pins, check your harness skills directory (<code>.claude/skills/</code>, <code>.cursor/skills/</code>, etc.) for directories prefixed with <code>i-</code>.</p>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
@@ -784,8 +803,5 @@
|
||||
|
||||
<script type="module" src="./app.js"></script>
|
||||
|
||||
<!-- impeccable-live-start -->
|
||||
<script src="http://localhost:8400/live.js"></script>
|
||||
<!-- impeccable-live-end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -124,7 +124,7 @@ export function renderCommandDemo(commandId) {
|
||||
<div style="display: flex; gap: 8px; align-items: baseline;">
|
||||
<span style="color: var(--spread-accent, var(--color-accent)); font-weight: 600; font-size: 12px;">3. Save</span>
|
||||
</div>
|
||||
<span style="opacity: 0.8;">Writes a <code style="font-size: 11px;">.impeccable.md</code> file with users, brand, aesthetic direction, and design principles. Every future command reads it automatically.</span>
|
||||
<span style="opacity: 0.8;">Writes a <code style="font-size: 11px;">PRODUCT.md</code> file with users, brand, aesthetic direction, and design principles. Every future command reads it automatically.</span>
|
||||
</div>
|
||||
</div>
|
||||
<div style="font-size: 12px; opacity: 0.5; margin-top: 2px; font-style: italic;">Run once per project. Then forget it exists.</div>
|
||||
|
||||
@@ -77,8 +77,5 @@
|
||||
<h2>Contact</h2>
|
||||
<p>Questions about this policy? Open an issue on <a href="https://github.com/pbakaus/impeccable">GitHub</a> or reach out to <a href="https://x.com/pbakaus">@pbakaus</a>.</p>
|
||||
</main>
|
||||
<!-- impeccable-live-start -->
|
||||
<script src="http://localhost:8400/live.js"></script>
|
||||
<!-- impeccable-live-end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Reference in New Issue
Block a user