Paul Bakaus
a89f7f5040
Feedback round from first review of the skill pages. Six concrete fixes:
1. Contain the auto-rendered SKILL.md in a distinct card.
The "skill itself" section was flowing straight into the editorial
wrapper above, making the two blocks read as one long mixed
document. Wrap the canonical body in .skill-source-card: white
paper background, mist border, rounded, with a small "SKILL.md"
badge header and an italic subtitle. Drop the old full-width
divider treatment; the card does the visual separation work.
2. Rewrite the /impeccable "do not fight the opinion" pitfall.
The old text said "fighting the opinion usually produces worse
output", which discouraged informed pushback. Replace with language
that explicitly encourages users with real reasons (brand guideline,
accessibility, user research) to push back; the skill raises the
floor, not overrules your judgment when you have evidence.
3. Move /onboard from create to refine.
Onboarding is refinement of empty states and first-run experiences,
not greenfield creation. Fixed in:
- scripts/lib/sub-pages-data.js SKILL_CATEGORIES
- public/js/data.js commandCategories
Both locations now list onboard under 'refine'.
4. De-dupe overdrive and animate.
- overdrive: "how it works" listed 7 techniques as bullets and then
"try it" listed 5 concrete examples using the same 7 techniques.
Collapse "how it works" into a tight paragraph and make "try it"
a specific scenario instead of a laundry list.
- animate: pitfalls repeated the "no layout properties" rule that
was already stated in "how it works". Drop the duplicate.
5. Remove outdated tutorial guidance.
getting-started.md said "Cursor needs Nightly channel plus Agent
Skills in Settings. Gemini CLI needs the preview version." Neither
is true anymore. Replace with a generic pointer to check the
harness's own skill docs.
6. Embed the live visual overlay in critique-with-overlay tutorial.
The tutorial now renders the same demo iframe the homepage uses
(/antipattern-examples/visual-mode-demo.html) inside step 2, with
a mac-window chrome frame that mirrors the homepage preview. New
.tutorial-embed CSS in sub-pages.css defines the header with
traffic-light dots + mono title, the iframe body (520px tall),
and an optional caption. The user now sees the overlay in action
before being asked to run it locally.
4.3 KiB
title, tagline, order, description
| title | tagline | order | description |
|---|---|---|---|
| Getting started | From zero to your first /polish pass in five minutes. | 1 | Install Impeccable, run /impeccable teach once to establish project context, and run /polish on something that already exists. The fastest path to seeing what Impeccable changes about AI-generated design. |
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.
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.
Step 1. Install
From the root of your project, run:
npx skills add pbakaus/impeccable
The installer auto-detects your harness and drops the skill files in the right place. It does not touch any existing code. You should see output like:
✓ Detected Claude Code (.claude/skills/)
✓ Installed 21 skills + impeccable foundation
Start your harness (or reload it) and type /. You should see /impeccable, /polish, /critique, and the other commands in the autocomplete.
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.
Run:
/impeccable teach
The skill will ask you a handful of 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".
- What should the interface feel like? Concrete adjectives. "Calm, trustworthy, fast" or "playful, bold, a little chaotic".
- Any visual references? Screenshots, sites, design systems you admire.
- Anti-references? Things the product should explicitly not look like.
Answer in your own words. The skill writes a .impeccable.md file with the answers. Every future skill call reads it automatically.
Open .impeccable.md and read what it wrote. Edit anything that does not feel right. The file is yours.
Step 3. Polish something
Pick a page that already exists. An about page, a settings screen, a pricing table, anything. Run:
/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
/critique the landing pageruns a full design review with scoring, persona tests, and automated detection. It is the best way to find what to fix next./audit the checkoutruns accessibility, performance, theming, responsive, and anti-pattern checks against the implementation. Useful before shipping./impeccable craft a pricing page for enterprise customersruns the full shape-then-build flow on a brand new feature.
Common issues
- The skill says "no design context found". You skipped step 2. Run
/impeccable teachfirst. - 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.