mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-15 07:36:50 +03:00
Fix website copy: shape/craft relationship, install sections, tutorial accuracy
- Clarify that /impeccable craft runs /shape internally (not the other way around) - Add three-mode documentation (freeform/craft/teach) to /impeccable page with anchor links - Add sidebar sub-links for /impeccable craft and /impeccable teach - Fix hallucinated npx impeccable live description in tutorial and visual-mode page - Remove nonsensical "Do not skip the independent part" from critique tutorial - Make Step 4 less prescriptive (users can fix all at once or one-by-one) - Improve CLI and browser extension install copy with specific features and use cases Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
0e4cc16620
commit
a024195ddb
@@ -6,7 +6,11 @@ tagline: "The design intelligence behind every other skill."
|
||||
|
||||
`/impeccable` is the foundation. It teaches your AI harness how to design, period. Every other command in this pack leans on it for design principles, anti-patterns, typography, color, and layout guidance.
|
||||
|
||||
Call `/impeccable` directly when you want freeform design with the full guidebook loaded. Call `/impeccable craft` for a shape-then-build flow with visual iteration. Call `/impeccable teach` once per project to set up design context.
|
||||
There are three ways to use it:
|
||||
|
||||
- **`/impeccable` (freeform)** -- Design with the full guidebook loaded. You describe what you want, and the model builds it with strong aesthetic opinions, anti-pattern awareness, and your project's design context. Best for when you already know what you want and just need it built well.
|
||||
- <span id="craft">**`/impeccable craft`**</span> -- The full shape-then-build flow. It starts by running `/shape` internally (a structured discovery interview about purpose, audience, and goals), then moves into implementation with visual iteration, checking the result in the browser until the polish is high. Best for brand-new features where you want to think before you build, without managing the steps yourself.
|
||||
- <span id="teach">**`/impeccable teach`**</span> -- One-time project setup. Runs a short discovery interview about your brand, audience, and aesthetic direction, then writes a `.impeccable.md` file that every future skill call reads automatically. Run this once per project before doing any design work.
|
||||
|
||||
## How it works
|
||||
|
||||
|
||||
@@ -19,7 +19,9 @@ The skill runs a structured discovery interview in conversation. It will not wri
|
||||
- **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 craft`, `/impeccable`, or any other implementation skill.
|
||||
You answer naturally. The skill asks follow-ups, not a form. At the end it produces a design brief: a structured artifact you can hand to `/impeccable` or any other implementation skill.
|
||||
|
||||
Note: if you want the full flow -- discovery interview, then straight into building -- use `/impeccable craft` instead. It runs `/shape` internally, then continues into implementation with visual iteration. `/shape` standalone is for when you want just the brief, so you can take it to whatever implementation approach you prefer.
|
||||
|
||||
## Try it
|
||||
|
||||
@@ -29,13 +31,7 @@ You answer naturally. The skill asks follow-ups, not a form. At the end it produ
|
||||
|
||||
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.
|
||||
|
||||
Then:
|
||||
|
||||
```
|
||||
/impeccable craft using the brief above
|
||||
```
|
||||
|
||||
The craft run will reference the brief at every decision. You should feel the difference compared to building without it.
|
||||
From there you can hand the brief to `/impeccable`, `/polish`, or any other skill. Or just use it as a reference while you build by hand.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ From your harness, run:
|
||||
/critique the pricing page at localhost:3000/pricing
|
||||
```
|
||||
|
||||
The skill kicks off two independent assessments in parallel. Do not skip the "independent" part. They are in separate sub-agents or separate tabs so one does not bias the other.
|
||||
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
|
||||
|
||||
@@ -57,19 +57,11 @@ Every outlined element has a floating label naming the rule that fired. Hover an
|
||||
|
||||
You have three ways to open it:
|
||||
|
||||
1. **[Chrome extension](https://chromewebstore.google.com/detail/impeccable/bdkgmiklpdmaojlpflclinlofgjfpabf)**: one-click activation on any page.
|
||||
2. **Inside `/critique`**: the skill opens the overlay automatically during the browser portion of the assessment.
|
||||
3. **Standalone CLI**: `npx impeccable live` starts a local overlay server, then you paste any URL.
|
||||
1. **[Chrome extension](https://chromewebstore.google.com/detail/impeccable/bdkgmiklpdmaojlpflclinlofgjfpabf)**: one-click activation on any page. Click the Impeccable icon in the toolbar and every anti-pattern gets highlighted instantly.
|
||||
2. **Inside `/critique`**: the skill opens a browser tab labeled `[Human]` with the detector active during the browser portion of the assessment. You do not need to do anything extra.
|
||||
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 we will use the standalone CLI so you can see it without depending on the extension.
|
||||
|
||||
In a new terminal:
|
||||
|
||||
```
|
||||
npx impeccable live
|
||||
```
|
||||
|
||||
This starts a server on `localhost:5199`. Open it. Paste the URL of your pricing page. The page loads inside an iframe with the detector script injected, and you get back the same overlay you saw above but on your own work.
|
||||
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
|
||||
|
||||
@@ -108,18 +100,15 @@ Questions to answer:
|
||||
- What does a user feel when they land here from an ad vs from search?
|
||||
```
|
||||
|
||||
## Step 4. Fix the findings in order
|
||||
## Step 4. Fix the findings
|
||||
|
||||
Do not try to fix everything at once. The report gives you a priority list. Work through it top to bottom.
|
||||
|
||||
For each issue:
|
||||
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 the fix in code.
|
||||
3. Reload. The overlay re-scans and the label for that rule should disappear.
|
||||
4. Move to the next.
|
||||
2. Make fixes in code (or ask the model to fix everything).
|
||||
3. Reload. The overlay re-scans and resolved findings disappear.
|
||||
|
||||
This loop (fix, reload, verify, next) is the reason the overlay matters. You see your fixes land in real time, and you never ship a "fix" that did not actually satisfy the rule.
|
||||
This feedback loop is the reason the overlay matters. You see fixes land in real time, and you never ship a "fix" that did not actually satisfy the rule.
|
||||
|
||||
## Step 5. Re-run /critique when you are done
|
||||
|
||||
@@ -137,4 +126,4 @@ If something still fires, fix it or write a suppression comment explaining why t
|
||||
|
||||
- **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**. The overlay runs inside an iframe. Some pages with strict frame-ancestors CSP will not load. Use the [Chrome extension](https://chromewebstore.google.com/detail/impeccable/bdkgmiklpdmaojlpflclinlofgjfpabf) in that case or run the detector from the CLI and apply findings manually.
|
||||
- **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.
|
||||
|
||||
@@ -471,6 +471,12 @@ main#main {
|
||||
background: transparent;
|
||||
}
|
||||
|
||||
.skills-sidebar-sub a {
|
||||
padding-left: 24px;
|
||||
font-size: 0.8125rem;
|
||||
color: var(--color-ash);
|
||||
}
|
||||
|
||||
/* ============================================
|
||||
OVERVIEW MAIN CONTENT
|
||||
============================================ */
|
||||
|
||||
+3
-3
@@ -413,7 +413,7 @@
|
||||
<svg class="install-step-arrow" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" aria-hidden="true"><path d="M9 6l6 6-6 6"/></svg>
|
||||
</summary>
|
||||
<div class="install-step-body">
|
||||
<p class="install-path-desc">Anti-pattern detection from the terminal. Scans HTML, CSS, JSX/TSX, Vue, and Svelte. Perfect for CI, pre-commit hooks, and one-off audits.</p>
|
||||
<p class="install-path-desc">Scan any file, directory, or live URL for anti-patterns from the terminal. Catches gradient text, AI color palettes, nested cards, low contrast, and 20+ more rules across HTML, CSS, JSX/TSX, Vue, and Svelte. Use it in CI pipelines, pre-commit hooks, or one-off audits to keep AI slop out of production.</p>
|
||||
|
||||
<div class="install-cmd-block">
|
||||
<div class="install-cmd-line">
|
||||
@@ -426,7 +426,7 @@
|
||||
</svg>
|
||||
</button>
|
||||
</div>
|
||||
<span class="install-cmd-note">Or use <code>npx impeccable</code> directly without installing.</span>
|
||||
<span class="install-cmd-note">Or use <code>npx impeccable detect src/</code> directly without installing.</span>
|
||||
</div>
|
||||
|
||||
<p class="install-path-link"><a href="https://www.npmjs.com/package/impeccable" target="_blank" rel="noopener">Full command reference on npm →</a></p>
|
||||
@@ -440,7 +440,7 @@
|
||||
<svg class="install-step-arrow" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" aria-hidden="true"><path d="M9 6l6 6-6 6"/></svg>
|
||||
</summary>
|
||||
<div class="install-step-body">
|
||||
<p class="install-path-desc">One-click anti-pattern detection on any live page: yours, staging, production, or anyone else's. Same detection engine as <code>/critique</code>, in your browser.</p>
|
||||
<p class="install-path-desc">Click the toolbar icon on any page and every anti-pattern lights up right where it lives: gradient text, purple palettes, nested cards, tiny body text, and the rest. Works on your localhost, staging, production, or anyone else's site. Great for spot-checking competitors, reviewing PRs visually, or just browsing the web with a sharper eye.</p>
|
||||
<p class="install-path-link"><a href="https://chromewebstore.google.com/detail/impeccable/bdkgmiklpdmaojlpflclinlofgjfpabf" target="_blank" rel="noopener">Install from Chrome Web Store →</a></p>
|
||||
</div>
|
||||
</details>
|
||||
|
||||
+1
-1
@@ -120,7 +120,7 @@ export const skillRelationships = {
|
||||
};
|
||||
|
||||
export const commandRelationships = {
|
||||
'shape': { flow: 'Create: Plan UX and UI through structured discovery', leadsTo: ['impeccable craft'] },
|
||||
'shape': { flow: 'Create: Plan UX and UI through structured discovery (included in /impeccable craft)' },
|
||||
'impeccable craft': { flow: 'Create: Full shape-then-build flow with visual iteration' },
|
||||
'impeccable': { flow: 'Create: Freeform design with full design intelligence' },
|
||||
'onboard': { combinesWith: ['clarify', 'delight'], flow: 'Create: Onboarding flows and empty states' },
|
||||
|
||||
@@ -197,6 +197,14 @@ ${tutorials
|
||||
`;
|
||||
}
|
||||
|
||||
// Sub-command links that appear as indented entries after their parent skill.
|
||||
const SUB_COMMANDS = {
|
||||
impeccable: [
|
||||
{ id: 'impeccable-craft', label: '/impeccable craft', href: '/skills/impeccable#craft' },
|
||||
{ id: 'impeccable-teach', label: '/impeccable teach', href: '/skills/impeccable#teach' },
|
||||
],
|
||||
};
|
||||
|
||||
// Then the skills, grouped by category.
|
||||
for (const category of CATEGORY_ORDER) {
|
||||
const list = skillsByCategory[category] || [];
|
||||
@@ -206,10 +214,17 @@ ${tutorials
|
||||
<p class="skills-sidebar-group-title">${escapeHtml(CATEGORY_LABELS[category])}</p>
|
||||
<ul class="skills-sidebar-list">
|
||||
${list
|
||||
.map((s) => {
|
||||
.flatMap((s) => {
|
||||
const isCurrent = current?.kind === 'skill' && current.id === s.id;
|
||||
const attr = isCurrent ? ' aria-current="page"' : '';
|
||||
return ` <li><a href="/skills/${s.id}"${attr}>/${escapeHtml(s.id)}</a></li>`;
|
||||
const items = [` <li><a href="/skills/${s.id}"${attr}>/${escapeHtml(s.id)}</a></li>`];
|
||||
const subs = SUB_COMMANDS[s.id];
|
||||
if (subs) {
|
||||
for (const sub of subs) {
|
||||
items.push(` <li class="skills-sidebar-sub"><a href="${sub.href}">${escapeHtml(sub.label)}</a></li>`);
|
||||
}
|
||||
}
|
||||
return items;
|
||||
})
|
||||
.join('\n')}
|
||||
</ul>
|
||||
@@ -491,7 +506,7 @@ function renderVisualModeMain() {
|
||||
<article class="visual-mode-method">
|
||||
<p class="visual-mode-method-label">Standalone CLI</p>
|
||||
<h3 class="visual-mode-method-name"><code>npx impeccable live</code></h3>
|
||||
<p class="visual-mode-method-desc">Starts a local overlay server, then loads any URL you paste in an iframe with the detector script injected. Works on your own dev server, a staging URL, or anyone's live page.</p>
|
||||
<p class="visual-mode-method-desc">Starts a local server that serves the detector script. Inject it into any page via a <code><script></code> tag to see the overlay. Works on your own dev server, a staging URL, or anyone's live page.</p>
|
||||
</article>
|
||||
<article class="visual-mode-method">
|
||||
<p class="visual-mode-method-label">Easiest</p>
|
||||
|
||||
@@ -92,4 +92,4 @@ Anything unresolved that the implementer should resolve during build.
|
||||
|
||||
{{ask_instruction}} Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions.
|
||||
|
||||
Once confirmed, the brief is complete. The user can now hand it to {{command_prefix}}impeccable craft to build the feature, or use it to guide any other implementation approach.
|
||||
Once confirmed, the brief is complete. The user can now hand it to {{command_prefix}}impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use {{command_prefix}}impeccable craft instead, which runs this skill internally.)
|
||||
|
||||
Reference in New Issue
Block a user