New /designing page: the missing "how do I actually use this tool?" story,
organized around a four-phase core loop. Start, iterate, polish, maintain.
Text-dominant editorial sections, cards are rare, spacing pulls from
DESIGN.md's scale only.
Hero runs as a single editorial spread: title and lede on the left,
a compass loop on the right. The compass is a thin ink circle with
cardinal phase labels at N/E/S/W, clockwise arrow glyphs at 45°
transit points, a slow orbiting accent dot, and an italic impeccable
wordmark in the middle. Collapses to vertical stack below 880px.
Phase sections below the hero are full width. Each opens with a
numbered eyebrow, italic Cormorant title (spine), and a 60ch sub.
Appendix sections (register cross-link, DESIGN.md interop, what to
avoid, CTA) use a quieter title tier in roman to separate spine from
supporting material. All separators are 1px mist hairline, no 2px
black rules; rhythm comes from variable padding and margins.
Adds /live-mode hero-frame polish, new top-nav entry (Home · Designing
· Docs · Anti-Patterns · Live · Overlay), footer link, and the server
route for /designing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Step 1 is now skill-only (the outdated "powers visual mode" claim
and the global CLI install are gone). Chrome extension stays at
step 3, the CLI moves to a new optional step 4 with a link to npm,
and "Stay updated" shifts to step 5. Step 2 collapses its three
numbered sub-steps into a compact command/caption table so the
"Use it" panel matches step 1's height instead of towering over it.
Also: keep code chips and the npm link on one line each (nowrap)
so the caption wraps only on natural prose.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Vertical 8-tab list ate ~430px of viewport on mobile; panel content
sat far below the fold. At ≤900px, the tab list becomes a sticky
horizontal scrollable pill strip (47px tall) under the header, with
edge-fade mask, pill-shaped buttons, ink-filled active state, and
the active pill auto-centered as rotation advances or users tap.
Desktop layout unchanged.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- why-panel tab swap is a proper opacity+transform crossfade (display:grid
stack area) instead of display:none jump; 650/800ms ease-out.
- tab progress indicator animates linearly (timer, not eased).
- Panel 01: dropped redundant "Every command reads this…" footer; moved the
commands meta into the visual as a right-side sidebar aside PRODUCT.md.
- Panel 02: "Browse the full catalog →" moved under the Gallery of Shame;
pattern category tabs are now always a single-row horizontal scroll with
JS-tracked edge-fade mask and chevron affordances; click centers the
selected tab inside the strip (never scrolls the page).
- Panel 04: "register" → "mode" in body, labels, meta for plain-language.
- Panel 05: removed redundant "Works in Claude Code…" meta.
- Panel 06: removed "Spec-compliant. Interoperable. Not a proprietary
sidecar." meta.
- .language-content grid gap reduced from --spacing-lg to --spacing-sm so
the commands palette sits closer to the section lead.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a coarse-controls ("Tune") popover that slides out from behind the
contextual bar via clip-path, showing 2-4 per-variant knobs (range / steps /
toggle) driven by a `data-impeccable-params` manifest. Range/toggle drive
CSS custom properties on the variant wrapper; steps toggle a data
attribute. Values reset per variant; on accept, current values are passed
through live-poll to live-accept as an `impeccable-param-values` comment
for the carbonize cleanup step to bake in.
Other live-UI work in this change:
- Theme-aware palette (barPaletteForTheme) now drives the contextual bar,
action picker, and tune popover. Dark sand on light pages, paper on
dark. Detection has a localStorage dev override for QA.
- Action picker chips get inline SVG icons (wand / bars / funnel / sparkle /
type ramp / circles / grid / devices / curve / star / bolt) stacked
above the label; selection state recolors via currentColor.
- Accept button switched to saturated site magenta with paper text.
- Cycle dots reworked: solid accent for active, neutral for arrived,
hairline ring for pending. No more magenta-on-gray noise.
- Tune chip sits in the cycling row with a count pill badge; open state
uses accentSoft bg + accent text (no ad-hoc white border).
- Popover uses the bar's palette with a deeper surface (surfaceDeep),
lives behind the bar via z-index so a 6px overlap reads as tucked under
it, and animates with clip-path inset() for reliable slide behavior.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Reorder and relabel all 8 tabs (Prevents AI slop, Brand + Product design, Ships code not mockups, Fluent in DESIGN.md, etc.)
- Flip every panel to title → body → visual → meta so the claim leads and the visual serves as proof
- Move "The Case" section header above the tab layout, matching the other sections
- Let panel visuals span the full right column; cap only the text at 60ch
- Wrap the right-side content in a paper card; strip .why-visual chrome to avoid nested cards
- Add a heading to panel 02 (Prevents AI slop) so it matches the others
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Remove section 03 (The Antidote) entirely as a standalone section.
Bring the original pattern list (patterns-tabbed via /api/patterns)
and gallery-stack-container back intact, and move them into a new
8th tab in The Case: "Anti-patterns, caught". The new tab panel
shows the list + gallery side-by-side on wide viewports, stacked on
narrow. Keeps the existing app.js wiring (renderPatternsWithTabs
and initGalleryStack both auto-discover via IDs).
Section numbers renumbered: Case 04→03, Live 05→04, Install 06→05,
Changelog 07→06, FAQ 08→07. Sticky nav updated to match.
Replaced the tall page-screenshot "before" images with the
self-contained inline visual examples from the /anti-patterns
catalog (VISUAL_EXAMPLES dict). Three before/after pairs:
1. Gradient Text — purple-blue "Build the Future" gradient text vs.
a solid italic Cormorant "Build the future." with magenta emphasis.
2. Side-Tab Cards — the ban signature, thick colored left stripe on
an otherwise neutral card vs. a hairline-bordered card with a mono
kicker and italic title.
3. Hero-Metric Template — the SaaS gradient "10M+" with tiny stats
vs. a single "+18.4%" italic insight with real explanation and
"from checkout fixes" causal tail.
Panels are now ~140px tall (was 4:3 aspect of full-page screenshots),
so the whole section is roughly half as tall. No large images, no
risk of the "Before" screenshots reading as Impeccable output. The
After panels sit on warm cream (brand surface) while the Before
panels use neutral cool white to further distance them visually.
The "wall of three screenshots" alone looked, at a glance, like
examples of pages made WITH Impeccable. Wrong signal. Replace each
card with a vertical before/after pair: anti-pattern screenshot on
top, hand-built refined alternative underneath. Pair labels use
colored pills (before = crimson, after = green) on the image corners
so the contrast is immediate. Three pairs shown:
1. Purple Gradients → warm editorial hero (cream bg, italic serif
title with magenta emphasis word, squared ink CTA, no gradient)
2. Cardocalypse → flat data table (mono labels, display numbers,
green delta, hairline rules between rows, no nested boxes)
3. Hero-Metric Template → one honest insight (single 52px italic
number with percent accent, body explanation mentioning the
actual reason, subtle sparkline)
Lead copy updated: "Before, and what Impeccable steers toward instead."
After mocks are pure inline HTML/CSS — no new image assets needed,
no font dependencies, fully respect brand (Cormorant italic display,
Instrument Sans body, magenta accent, warm cream bg, sharp CTAs).
Previous layout was a wall of text (three numbered stat rows plus a
side gallery). User feedback: "seeing is believing." Drop the stats
entirely, lead with three big anti-pattern screenshots in a 3-up grid
(Purple Gradients / Cardocalypse / Hero-Metric Template), tight
one-line lead above, footer row with "Browse all 25" link + a small
mono meta line that still carries the key claims (deterministic rules,
LLM layer, browser overlay) in a single sentence.
Images use 4:3 aspect, hover lifts them slightly with a magenta-soft
outline glow, labels are italic display face + mono accent number.
The whole section now reads at a glance: headline + three pictures +
one link.
Content: rewrite the stats to actually sell the differentiator.
- Row 1: "25 Named anti-patterns" — vs. the short prose lists in
comparable skills (Anthropic's frontend-design, assorted "AI design"
skills).
- Row 2: "2 Detection layers" — deterministic (source + DOM, no LLM)
+ LLM semantic pass via /impeccable critique.
- Row 3: "3 Surfaces" — CLI for PR gating, Chrome extension on any
page, overlay inside /impeccable critique.
Lead copy amplified: "list a handful of don'ts in a document and hope
the model remembers" vs. "actively detects them."
Layout: grid-template-columns is now minmax(0, 1fr) minmax(320px,
420px), align-items: start. The row fills the section's full width,
left column sits left-aligned against the intro text, gallery stays
to the right in its natural 320-420px range. Stat numbers shifted
to magenta accent + bolder 3rem italic, rows separated by a dashed
hairline, with bold ink lead-words ("Named anti-patterns" etc.) in
the descriptions for scannability.
- Drop the black rule above the support list (it read as a hard hat
over the column).
- Drop the phase-caption strip below the frame (the demo already
carries its own state visually; the narrated loop underneath was
noise).
- Rewrite the four support cells with stronger POV:
- Start: the actual commands, /impeccable live and stop.
- Your agent, your code: emphasises that it's the same AI you've
been working with, reading your real project context, generating
real edits.
- Accept = write: canvas-like iteration, production output. The
point almost no other AI design tool can claim.
- Skill-native: no external tools or IDE extensions, works across
every harness the skill targets.
- Drop CSP-patch bullet (edge case, not worth homepage real estate).
- Drop the "Accepts into ... via HMR" framing — accepts work because
of the skill loop, not because of HMR per se.
Four responses to feedback:
1. Language: fold "Pick any command to see it in action / Full command
reference →" into the section-lead. The whole commands-header row
is gone; the fisheye panel now sits much closer to the lead copy.
2. Antidote: full two-column editorial split. Left column carries the
lead + a three-row stats block (25 / 6 / 3) and the "Browse full
catalog" CTA as a squared editorial link. Right column is the
Gallery of Shame card stack. No more empty right-of-gallery void.
3. The Case: tab labels switch from Cormorant italic serif to body
sans. Tab numbers stay mono. Less aesthetic noise, cleaner reading.
4. Live Mode:
- Layout split: the frame now sits in the left column with its
caption; the support list ("Works on / Accepts into / CSP /
Overlay") moves to a narrow right column, rule-delimited, with
magenta-kicker-above-ink style per cell. Under the support list
on desktop, stacks on mobile.
- Skeleton page: nav bar (logo + 3 links + CTA) plus heading +
body lines drawn in at 30% opacity behind the target card, so
the iteration reads as "I clicked an element on an actual page."
- Variant cards rewritten with distinct design language per card:
V1 editorial column (rule-top, italic display, text-link button),
V2 brutalist ink ticket (ink slab, magenta accent stripe, stamp
glyph, sans bold), V3 playful dashed postcard (stickers, italic
Cormorant, pill CTA). The demo now actually shows three visually
different directions instead of three similar cards.
Antidote (task b): drop the duplicated pattern tabs (content lives on
/anti-patterns for the full list). Keep the Gallery of Shame as the
signature visual and add a "Browse the full catalog" link underneath.
Section is roughly 40% shorter vertically.
Live Mode demo (task faithful): rewrite to match the real picker flow
one-for-one. Now two separate bars:
- Global bar: dark pill, bottom of the frame, persistent for the
whole session. / + Pick (active) + Detect + DESIGN.md + divider + ✕.
- Contextual bar: LIGHT paper-backed pill that floats above the
picked element, mirroring buildConfigureRow() in live-browser.js.
Dark command pill, transparent input, ×N count, magenta Go button.
Morphs through configure → generating (spinner) → cycling (prev /
counter / next / discard / Accept) → accepted (green ✓ written to
source).
Contextual bar positions itself below the target when space allows,
else above. New JS positionCtx() mirrors the real positionBar()
logic. prefers-reduced-motion still freezes on a representative
"cycling, variant 3" still.
Timeline unchanged in steps but step captions updated to match the
new two-bar split ("Contextual bar appears." etc.).
Two homepage tweaks:
- Section 02 (The Language) gets a pill-style Palette / Periodic view
toggle at the top-right of the intro row. Palette (fisheye command
gallery) is default; Periodic (the periodic table) is behind a tab
click. Collapses the section's vertical footprint substantially
without losing the signature periodic-table visualization.
- Section 04 renamed "Why Impeccable" → "The Case". Matches the
editorial voice of "The Language" / "The Antidote" / "The Editors"
(changelog signature). Sticky nav label Case.
Section 05 is now "Live Mode" with a self-contained real-DOM animated
demo loop. Browser chrome + stage + picker bar + simulated cursor,
running through the full Live Mode flow:
hover → outline → click → open command picker → pick "delight" →
type "more playful" → draw stroke → Go → generating → three
variants cycled → accept → write-to-source confirmation → reset
Three distinct card variants morph in place so the cycling reads as
real iteration, not a slideshow of the same card. Picker bar states
(idle / configuring / generating / cycling / accepted) are driven by
data-phase and matching CSS selectors. Simulated cursor animates
between targets on an expo-out curve; annotations draw a scribble
stroke and pop a comment tag. IntersectionObserver gates the timeline
so it only plays while visible, and prefers-reduced-motion freezes
on a cycling / variant 3 still.
Supporting row below the frame adds the three honest limitations:
frameworks supported (Vite/Next/SvelteKit/Astro/Nuxt), writes to real
source via HMR, CSP-strict apps get a one-time dev-only patch.
Top-nav rename "Visual Mode" → "Overlay" (points at /visual-mode
which is still the overlay-focused sub-page). Sticky section-nav
updated too.
New file: public/js/components/live-demo.js with the timeline driver.
Three polish items on the Why Impeccable section:
- Move the "04 / Why Impeccable" section header into the left column
next to the tab list. The right-side panel now aligns vertically
with the heading instead of sitting offset below it.
- Replace the outer border-top + per-tab border-bottom with an
adjacent-sibling combinator (li + li). No more hairline above the
first tab or below the last one.
- Rework the active-state progress bar. Previously the is-active
border-left-color was fully magenta, which hid the countdown
animation underneath it. Now the active state is driven entirely
by a 2px progress column that either sits full-height (paused or
user-selected) or fills from top to bottom over the cycle window
on a gentle ease curve. The countdown is actually visible now.
Per reference/live.md's carbonize instructions (which I should have
followed immediately after the accept event):
- Moved the inline @scope CSS into public/css/workflow.css, rewritten
to use the real .why-visual--v2 class instead of
[data-impeccable-variant="2"].
- Removed the <style data-impeccable-css="afb9794d"> block from index.html.
- Removed both impeccable-carbonize-start / -end marker comments.
- Unwrapped the <div data-impeccable-variant="2" style="display: contents">
wrapper around the accepted variant content.
- Dropped the dead @scope rules for variants 1, 3, 4 entirely.
Only load-bearing element classes remain (why-visual--v2, v2-side,
v2-label, v2-canvas-*, v2-new-*) and they're all styled via the
central stylesheet now.
Alignment: .why-section had its own max-width + horizontal padding,
which made the whole section sit inside a narrower column than every
other section. Drop the extra wrapping; match the .antidote-section /
.visual-mode-section pattern (padding: 2xl 0, border-top).
Panel 04: scrap the "your IDE + AI agent" browser-chrome surface
(confusing, implied a code editor with a fake browser top bar, and
never mentioned what the point actually is). Replace with two side-by-
side tiles: dark "Your AI agent" tile + warm "Your browser / Live Mode"
tile, joined by a magenta "+" glyph. The line underneath lands the
point: two surfaces you already have open, zero handoff.
Addressing feedback that the first round didn't sell the differentiation:
01 Intentional design: scrap the "generic AI card vs warm card" comparison
(the slop card actually looked good, which undermined the point). Show
PRODUCT.md as a real file with fields filled in (Users, Register,
Brand voice, Anti-references) and a pulse-dot footer signaling it's
loaded on every command. The point is that Impeccable knows specific
things about the product before it designs anything.
03 Production codebases: expand the terminal from a single "reading
DESIGN.md" line to a full codebase walk. Tokens from tokens.css,
merged tailwind theme, 34 components listed with variants inferred,
DESIGN.md as one of many inputs. DESIGN.md is shallow; the real work
is traversing source.
04 Where you code: scrap the card grid. Replaced with a two-row
waterfall-vs-unified flow. Old way (greyed, strikethrough): Figma →
Handoff → Ticket → Engineer → QA drift. New way: a single surface
with Design / Code / Ship chips inside a fake IDE chrome. Pulls the
real argument instead of just showing logos.
05 DESIGN.md: picker-sidebar-style rich tiles. Accent color with
8-step tonal ramp, Aa specimens for display + body, component chips +
input preview. Stitch spec badge up top. Matches the visual vocabulary
of the live-mode DESIGN.md sidebar.
Panels 02, 06, 07 unchanged per feedback that they were working.
Per-panel storytelling visualizations, pure HTML/CSS, no image assets:
- 01 Intentional design: "Generic AI" dark/purple gradient card vs.
warm editorial card with /impeccable vocabulary side by side.
- 02 Brand and product, both: tiny brand mock (italic display headline)
vs. product mock (mono/stats rows).
- 03 Production codebases: dark terminal showing /impeccable polish
reading DESIGN.md tokens and component APIs.
- 04 Where you code: prompt bar with blinking caret + 4×2 grid of
harness logos (Claude, Cursor, Codex, Gemini, Copilot, Antigravity,
Kiro, OpenCode).
- 05 DESIGN.md: a file-view of the six Stitch sections with a
"Stitch spec" badge, plus an interop tagline.
- 06 CI/CD: terminal showing `impeccable detect` failing CI with
three issues and exit 1.
- 07 Chrome extension: browser chrome + floating extension popup
listing detections and two magenta outline boxes over "page content".
Auto-rotation: 7s per tab, pauses on hover, stops entirely on any
click/keyboard interaction (user-initiated navigation wins). Thin
magenta progress bar animates on the active tab's left accent as
the rotation progresses. IntersectionObserver gates the whole timer
so it only runs while the section is on screen. prefers-reduced-motion
disables the auto-rotation and the progress animation.
Dropped the "Seven reasons..." lead line.
New section 04 with a vertical tab list on the left and a panel on the
right. Seven items covering the actual differentiators:
1. Intentional design — PRODUCT.md + DESIGN.md + shape as the opposite
of one-shot-mock tools.
2. Brand and product, both — the register split, called out against
frontend-design-style single-mode skills.
3. Production codebases — reads your design system, daily-driver.
4. Where you code — IDE-native, no canvas, no handoff.
5. DESIGN.md — Google Stitch spec-compliant, interoperable.
6. CI/CD-ready — CLI + JSON output for PR gates.
7. Chrome extension — 25 checks, one click, any page.
Section numbers bumped: Visual 04→05, Install 05→06, Changelog 06→07,
FAQ 07→08. Sticky nav updated to match.
Arrow-key tab navigation, aria-selected, hidden attr on inactive
panels, subtle fade on switch, respects prefers-reduced-motion.
Vertical layout on desktop, stacked on mobile.
The DO/DONT extractor in readPatterns stopped finding anything after
the skill went human-authored (new SKILL.md uses plain bullets, one-word
section headings, no DO:/DON'T: prefixes). Replace the extractor with
a hand-curated category list: six categories, three or four DOs and
DON'Ts each. Editorial tone, tight, deliberately a teaser — the full
catalog still lives on /anti-patterns.
The legacy SKILL.md parser is retained in the file as _legacyReadPatterns
in case we want to revive it later with a different format.
Small CSS fix: .faq-question was display:flex with justify-content:
space-between, so inline <code> in a summary got treated as its own
flex item and pushed apart. Switched to relative+absolute positioning
so the + icon sits in the right margin and text flows naturally.
Changelog font size reduced to 0.9375rem for the expanded v3.0 entry.
New FAQ entry on pinning standalone commands back. Pin section added
to /docs/impeccable editorial.
- 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).
Three related site scroll bugs:
1. initAnchorScroll and initHashTracking both called scrollTo with
`behavior: 'auto'`, which defers to CSS `scroll-behavior`. Because
sub-pages.css set `html { scroll-behavior: smooth }`, every anchor
jump and reload-hash-restore animated — despite a code comment
explicitly stating "Instant anchor scroll — no smooth scrolling".
Switch to `behavior: 'instant'` so the JS wins.
2. The reload-hash restore used a fixed `setTimeout(100)` to compute
target position. At 100ms, async Google Fonts (Cormorant Garamond
italic) has not swapped in, so `getBoundingClientRect().top` is
computed against fallback metrics and mislanded by hundreds of
pixels. Retry on `document.fonts.ready` and on window `load`.
3. Remove `scroll-behavior: smooth` from sub-pages.css entirely —
it was silently fighting the JS and made long-page anchor clicks
feel sluggish.
- Bump skills plugin version 2.1.1 -> 3.0.0 (plugin.json, marketplace.json,
harness SKILL.md files). CLI and Chrome extension unchanged.
- Remove prefixed universal zip bundle and all related code:
factory.js prefix/outputSuffix options, zip.js variant pass, utils.js
prefixSkillReferences, the "universal-prefixed" entry in
download-providers.js, and the matching test suite in utils.test.js.
- Redesign Get Started step 1 "Install the skill and CLI": two terminal
rows (npx skills + npm i -g impeccable) with paired notes, drop the
Recommended badge.
- Collapse "Other install methods" back into a <details> element so the
primary install path is the first thing users see.
- Simplify step 3 to "Add the Chrome extension": remove the CLI tool
block (now in step 1), use standard .btn .btn-primary for the CTA so
it matches other primary buttons (square corners, accent slide-up
hover), and lay out the preview screenshot next to the button instead
of stacked so the screenshot no longer dominates vertical space.
- CLAUDE.md: rewrite with v3.0 architecture, the "no em dash also means
no --" rule, the harness-dirs-are-tracked gotcha, the named-export
test-spy warning, and the evals inline-skill.ts sync note.
- AGENTS.md, DEVELOP.md: drop prefixed variant references.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Biggest change in a while. Users previously had 18 standalone skill
entries cluttering their /menu; now they have one entry (/impeccable)
that routes to 20 specialized commands via argument dispatch. The pin
mechanism (/impeccable pin audit) restores standalone shortcuts on
demand for commands users hit all the time.
## Architecture
- Single /impeccable skill with command router section in SKILL.md
- 20 commands served via reference files under source/skills/impeccable/reference/
- /impeccable pin <command> creates a lightweight redirect shim so users
who prefer /audit, /polish, etc. can still have them
- Context gathering (teach) auto-runs on first use
- command-metadata.json is the single source of truth for command
descriptions, argument hints, and relationships
## Site rewrite
- Docs URL: /skills renamed to /docs (with /skills permanent redirects)
- Homepage hero frames Impeccable as "one skill with 20 commands"
- "Get Started" split into 50/50 install + how-to-use with editorial
numbered steps, /impeccable shown as the home command with three modes
- New /docs overview: home command hero card + dense category rows
matching the old cheatsheet density, with leads-to/pairs-with/
combines-with relationship metadata served from a shared source
- Cheatsheet merged into /docs, /cheatsheet redirects
- Magazine spread and mobile cards show /impeccable as a stacked
namespace label above the command name at full display size
- Periodic table updated with craft/teach/extract as first-class cells
- Skill detail pages generate from reference files, with an editorial
wrapper per command for tagline + body
- Tutorials and anti-patterns pages updated to use /impeccable <cmd>
## Build system
- Dead code removed (scripts/lib/transformers/shared.js)
- Build log wording fixed ("1 skill" not "1 skills (1 user-invocable)")
- generateApiData fallback branch removed (throws loudly if metadata
missing instead of silently degrading)
- Commands API includes editorial tagline alongside the long description;
UI surfaces prefer tagline for human display, description for auto-
trigger keyword matching
## Gitignore
- Added .claude/scheduled_tasks.lock, .claude/settings.local.json to
ignore list (local Claude Code state that should not be tracked).
- Harness skill directories (.claude/skills/, .agents/skills/, etc.)
remain tracked by design: npx skills reads them from this repo at
install time and they enable clean submodule use.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add max-width: 56ch to install-step-body so long descriptions
don't run edge to edge
- Rewrite FAQ update answer as a scannable list instead of dense
paragraphs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- 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>
The /visual-mode sub-page rules added in 27d1b13 duplicated
.visual-mode-preview (and its header/dot/title children) in
sub-pages.css with a max-width + margin: 0 auto. Because sub-pages.css
loads after main.css on index.html, those styles won on the homepage
too. Auto margins on a grid item disable justify-self: stretch, so the
preview collapsed to the iframe's 300px intrinsic width instead of
filling its 3fr cell in .visual-mode-demo.
Scope the rules to .visual-mode-page so they only apply on the sub-page
and the homepage falls back to main.css's .visual-mode-preview rule.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The min-height: calc(100vh - var(--site-header-height)) added earlier
so the sticky sidebar's border-right divider reaches the bottom of
the viewport on desktop was applying on mobile too. On mobile the
sidebar is static (not sticky) and collapses behind a toggle, so the
min-height reserved a full viewport of empty space above the main
content whenever the menu was collapsed. The result: opening
/anti-patterns on mobile showed just the 'Sections' dropdown in the
first screen, then a blank viewport, then the rules below the fold.
Wrap the min-height rule in a min-width: 921px media query so it only
applies on desktop, matching the breakpoint that switches the layout
to the two-column grid.
The 'In the wild' section at the bottom of /anti-patterns was
mischaracterizing synthetic fixtures as real examples and was buried
deep in a taxonomy of detection rules. The specimens belong somewhere
that frames them as what they actually are: live pages you can click
into to experience Visual Mode. Split them off into a new top-level
page that also finally gives Visual Mode first-class treatment.
- New /visual-mode page, top-level nav item, single-column layout (no
sidebar). Structure:
1. Editorial header with an "Live detection overlay" eyebrow.
2. Live iframe embed of visual-mode-demo.html inside mac-window
chrome, same preview component the homepage uses.
3. "Three ways to run it" section with three method cards:
- /critique runs the overlay inside its browser pass
- `npx impeccable live` starts a standalone overlay server
- Chrome extension, marked coming soon, with a cream bg
4. "Try it live" gallery of the 11 synthetic specimens as
clickable cards. Each links to /antipattern-examples/{id}.html
where the detector script is already injected so the reader
lands on a live overlay.
- scripts/build-sub-pages.js: new renderVisualModeMain(); visualMode
added to outDirs; generator loop writes /visual-mode/index.html.
- server/index.js: new /visual-mode route serving the generated file.
- Top nav on every page gains 'Visual Mode' between Anti-Patterns
and the GitHub pill. Updated the partial + all 4 hand-authored
HTML pages.
- .gitignore adds public/visual-mode/.
- /anti-patterns: 'In the wild' section and its TOC entry removed.
Replaced with a one-line pointer at the end of the lede: "Want to
see them live on real pages? Try Visual Mode." GALLERY_ITEMS stays
in the catalog file (now used by /visual-mode only).
- public/css/sub-pages.css: new .visual-mode-page-body + .visual-mode-*
classes. Ports the mac-window chrome (dots + mono title) from
main.css, adds three-card method grid, and reuses the existing
.gallery-card styles for the specimen list.
Clean up a few em-dashes in the catalog (block comments + one visible
visual example) so the build-time validator stays clean.
Server restart required to pick up the new /visual-mode route.
Two fixes from the review.
1. Rule id chip hidden. The internal slugs (e.g. 'border-accent-on-rounded')
are not useful to readers, only to detector code. Drop the
.rule-card-id element from the card head entirely. The DOM id on
the article stays so rules can still be anchor-linked.
2. Merge /gallery into /anti-patterns and drop 'Gallery' from the nav.
'Gallery' in the top nav reads as 'things built with impeccable'
when it is actually a curated collection of AI-generated UI in the
wild — the complement to the rule catalog above.
- Add GALLERY_ITEMS to content/site/anti-patterns-catalog.js
(11 entries, same ids and copy as the old gallery.html)
- Render a new 'In the wild' section at the bottom of
/anti-patterns with a card grid of the 11 specimens, each linking
to its standalone live example under /antipattern-examples/{id}.html
- New .gallery-card CSS: square thumbnail, italic display title,
charcoal body, hover lifts the card and tints the title accent
- Add an 'In the wild' entry to the anti-patterns TOC sidebar so
readers can jump to it
- Drop the 'Gallery' link from the top-level nav in the shared
header partial and the 4 hand-authored HTML pages. The old
/gallery route still serves its page directly (for bookmarked
links), but the nav no longer advertises it and the gallery page
itself now marks Anti-Patterns as the active nav item.
Six fixes from the first-pass review.
1. Visuals for all 13 LLM-only rules. The catalog now ships a preview
snippet for every card: Syne-style display, monospace-as-technical,
dark-mode-default, everything-in-cards (nested), identical card
grids (literal 3x2), hero metric layout (big number + gradient +
supporting stats), glassmorphism (backdrop-filter on a gradient),
sparkline decoration, generic drop shadows (three rounded squares),
modal reflex (backdrop + centered dialog), every-button-primary,
redundant-headers, mobile-amputation. Every rule card now has the
same ~160px preview treatment.
2. Lede font normalized to match skill detail pages. .sub-page-lede
dropped from clamp(1.0625, 1.6vw, 1.25rem) to clamp(1, 1.4vw, 1.125rem)
so the paragraph under the anti-patterns title is the same size as
the tagline on every other /skills page.
3. "How to read this" legend collapsed into a <details> disclosure.
Summary is a single compact row with the title + chevron, padding
14px vertical. Body appears when opened, same content as before.
Chevron rotates on open.
4. Visual example height bumped 140px -> 160px for more breathing
room with the complex snippets.
5. Wider grid on the anti-patterns page. .anti-patterns-content no
longer has a 820px max-width; only the header (720px max) and
legend (720px max) are capped. The rule card grid fills the full
main column width on wide viewports, so 38 cards stop wasting
horizontal space.
6. Sidebar divider extends to the bottom of the viewport. Add
min-height: calc(100vh - var(--site-header-height)) to .skills-sidebar
so the sticky column fills the full viewport vertically regardless
of content height, and the border-right reaches the footer.
Three additions to the anti-patterns catalog page, all sourced from a
new content/site/anti-patterns-catalog.js file so the user's parallel
edits to src/detect-antipatterns.mjs don't conflict with display metadata.
1. Detection layer badge per rule. Three layers:
cli - static analysis or jsdom. Runs from `npx impeccable detect`
on files, no browser required. 23 of 25 current rules.
browser - needs real browser layout (getBoundingClientRect).
Runs via the browser extension or Puppeteer, not the
plain CLI. Only 2 rules: cramped-padding and line-length,
as documented in tests/detect-antipatterns-browser.test.mjs.
llm - no deterministic detector. Flagged by /critique's LLM
review pass. 13 rules live only in the skill's DON'T list.
Each card renders a mono pill with the layer label, color-coded per
layer (neutral mist for CLI, blue tint for browser, amber tint for LLM).
The How-to-read legend grows a dl explaining what each layer means.
2. Inline visual example per detected rule. All 25 detection rules get
a ~140px tall preview area at the top of the card showing the bad
pattern as live HTML (cream background, self-contained inline styles).
Visuals for side-tab, gradient-text, dark-glow, nested-cards, and the
rest let you see what the detector is actually flagging. LLM-only
rules ship without visuals for now; their card bodies take the full
card height.
3. LLM-only rules merged into the sections. Parsed out from
source/skills/impeccable/SKILL.md DON'T lines that the detector
doesn't cover: Syne, monospace-as-technical, dark-mode-default,
everything-in-cards, identical-card-grids, hero-metric-layout,
glassmorphism, sparkline-decoration, generic-drop-shadows,
modal-reflex, every-button-primary, redundant-headers,
mobile-amputation. Each renders like a detection rule card but
shows the 'LLM only' layer badge and has no rule id chip. They
slot into the same section groups as detected rules (Interaction
and Responsive sections added to the section order so these get
real headings).
- scripts/lib/sub-pages-data.js: imports the catalog, enriches
detected rules with { layer, visual }, appends LLM_ONLY_RULES with
layer: 'llm'. Re-exports LAYER_LABELS and LAYER_DESCRIPTIONS for
the generator.
- scripts/build-sub-pages.js: renderRuleCard adds the visual block
and the layer badge; LLM rules drop the rule id chip since their id
is just an internal slug. groupRulesBySection now extends the
primary order with whatever extra sections rules reference.
- public/css/sub-pages.css: .rule-card now has a .rule-card-visual
preview area on top with border-bottom, body section below. New
.rule-card-layer pill styling per layer. Layer legend dl using a
2-column grid for badge -> description.
Dev server serves 38 total cards (25 detected + 13 LLM) across 8
sections: Visual Details, Typography, Color & Contrast, Layout & Space,
Motion, Interaction, Responsive, General quality.
The accent-dim background fill on active items was too loud. Keep
only the border-left accent, ink color, and bold weight. Hover tint
on other items still works as a subtle interactivity hint.
The previous attempt put the active-state border at margin-left: -14px
so it would sit in the layout gutter while keeping the link text
aligned with the header logo. Problem: .skills-sidebar uses
overflow-y: auto, and per CSS spec that coerces overflow-x from
visible to auto too, which clips any content outside the column. The
border was being painted and then clipped, so the user saw nothing.
Rework:
- Border now sits inside the normal flow. padding: 4px 0 4px 12px
with a 2px border-left means link text is 14px inset from the column
edge. Group titles pick up the same 14px padding-left so the two
align vertically.
- Add a subtle accent-dim background on the active item (not just the
border) so the cell reads as highlighted, not just marked.
- Add a hover background tint so items feel interactive.
- Remove the duplicate .skills-sidebar-list a[aria-current] block that
was left over from the previous rewrite.
Trade-off: links are now 14px to the right of where the header logo
sits (before, they aligned). Worth it: the active state is now clearly
visible on both desktop and mobile.
Three docs sidebar improvements.
1. Collapsible mobile menu. The sidebar on narrow viewports used to
dump 21 skill links and 2 tutorial links inline above the content,
forcing a long scroll past the nav. Add a toggle button at the top
of the sidebar that shows the current page label (e.g. "/overdrive"
or "Getting started") plus a chevron, and collapses the menu behind
it on mobile. Click the button to open/close. On desktop (>=920px)
the toggle is hidden and the menu shows unconditionally as before.
Pure aria-expanded state driven by a small delegated click handler
in render-page.js.
2. Active-state breathing room. The left-border accent on the current
sidebar item used to sit 2px from the text, which felt cramped. Pull
the border 14px to the left via margin-left and push the text 12px
to the right via padding-left. The net result: the accent bar sits
in the layout gutter, the text keeps its alignment with the brand
logo in the header, and there's now 12px of comfortable space
between the border and the text.
3. Active state visibility. The same change makes the accent bar more
visible on desktop, since it no longer hugs the text. 'aria-current'
was already being set correctly on /skills/* and /tutorials/* pages;
the bar just looked too subtle at 2px of clearance.
The demo's Before/After labels and the descriptive caption were on two
separate rows below the card. Merge them into one row: Before pinned
left, caption centered in the middle, After pinned right.
- Move the caption <p> inside .split-labels between the two label spans.
If a skill has no caption, emit an empty <span> placeholder so the
grid still has three cells and Before/After sit at the edges.
- Switch .split-labels from flex space-between to a 3-column grid
(auto minmax(0,1fr) auto) with baseline alignment. Before is
justify-self: start, After is justify-self: end, caption is
justify-self: center.
- Reset the caption's typography inside the grid (default body font,
not mono; text-transform: none; letter-spacing: 0) since it inherits
the label row's monospace caps by default.
The eyebrow ('Drag or hover to compare') was a sibling of
.split-comparison, sitting at the left edge of the outer .skill-demo
section. Because .split-comparison has 32px padding, the visible card
inside sat 32px to the right of the eyebrow, creating a visible
indentation mismatch. Move the eyebrow inside .split-comparison so it
inherits the same 32px offset and aligns with the card's left edge
(same as how .split-labels and .skill-demo-caption already align).
Note: the HTML order inside .split-comparison is now eyebrow -> container
-> labels -> caption, which matches the homepage's before/after demo
flow (card -> BEFORE/AFTER -> descriptive caption).
Two problems with the previous hero pass:
1. The whole .skill-detail was capped at 720px, so the hero grid got
squeezed into that same width. The demo column tried to hold its
fixed 360px height but lost width, forcing the split-container into
a portrait aspect ratio with no room for the intended 500x360
landscape layout.
2. The grid used grid-template-columns: minmax(0, 1fr) auto, which
meant the demo column was sized to its content (max 564px) but
competed with the text column for the shared 720px. The demo got
cramped instead of floating as a proper hero module.
Fix: drop the max-width from .skill-detail itself. Apply it per body
section (.skill-detail-hero, .skill-detail-editorial, .skill-source-card,
.skill-references) so each one keeps its readable 720px cap by default
but the hero can override it. At >=1280px viewport, .skill-detail-hero--has-demo
switches to a grid with a FIXED 564px demo column (guaranteeing the
split-container holds its 500x360 landscape) and a minmax(0,1fr) text
column, capped at max-width: 1200px. The editorial body below still
renders at 720px for line length.
Below 1280px the hero stacks as before (header then demo) within the
720px body column, same layout as a minute ago.
Two visual fixes to the skill detail demo block.
1. Remove the 24px padding from .split-content. This padding was the
'persistent indentation' visible in the screenshot: it created a
white band between the container border and demo content that had
its own card background. The overdrive demo (which fills the
container via absolute canvases and 100% divs) lost some of its
bleed to the padding; the polish-style demos (small centered cards)
don't need it because .split-content already uses flex centering.
2. Restructure the skill detail header into a .skill-detail-hero
wrapper that holds both the header text and the demo block.
- At >=1100px viewport: switch to a grid (minmax(0,1fr) auto),
text column on the left, demo on the right, align-items:center
so the eyebrow/title/tagline center with the demo vertically.
The demo floats as an editorial hero element alongside the title.
- Below 1100px: stack (demo under the header) with clamp-based
spacing between them. Same visual as before, just now inside the
hero wrapper.
- skill-detail-hero--has-demo class so skills without a demo
(/shape) keep the single-column layout with no grid quirks.
Caption was sitting with a ~56px gap below the labels (32px container
padding-bottom + 24px caption margin-top). Move the <p> inside
.split-comparison so the padding wraps the caption too, not separates
it from the labels. Drop caption margin-top from 24px to 12px and tone
the color down from charcoal to ash + 0.8125rem to match the rest of
the supporting-text rhythm on these pages.
Two issues with the previous buffer pass:
1. The buffer was too small (20px) to feel forgiving.
2. The visible box had a cream background while the buffer area showed
the paper page background, creating a 2% contrast inset that read
as a card-inside-a-card border.
Bump the buffer to 32px per side (64px total) so the demo stops at
500px visible with 564px max-width. Change .split-container background
from cream to paper so it blends into the page and the buffer area is
genuinely invisible. The demo box is now defined by its 1px mist border
and 12px radius alone; individual demos still provide their own
background colors on top via the inline before/after HTML.
Ported the homepage's padding-margin trick: .split-comparison now has
20px of padding around the visible box, with a matching negative
top/bottom margin so the padding does not affect layout flow. The
pointer event listeners move from .split-container to .split-comparison
so the hover tracking engages inside the buffer and only resets when
the mouse leaves the full padded area. Percentage math still reads
.split-container.getBoundingClientRect() so the divider position stays
aligned with the visible box.
This matches how the landing-page split demo feels: graze the edge
and the divider holds; leave the box entirely and it eases back.
Four issues reported on /skills/overdrive (and every other skill demo):
1. The demo block was centered inside the content column, looking odd
against the otherwise left-aligned page. Drop 'margin: 0 auto' from
both .split-comparison and .split-container, and remove the nested
max-width so the whole demo left-aligns at 500px max-width with no
centering.
2. The BEFORE and AFTER labels were stretching beyond the demo box
because .split-comparison (560px) was wider than .split-container
(500px) and .split-labels was using justify-content: space-between
across the wider parent. Collapse the two max-widths to a single
500px cap so the labels now sit flush with the container edges.
3. The label row was sitting way below the demo (16px margin-top plus
the height-stretched container). Tighten margin-top to 10px.
4. The inline split-compare handler only supported click-and-drag. The
homepage effect also tracks hover on devices with hover:hover, so
the mouse sweeps the divider and leaving the box eases it back to
the default. Port that behavior: matchMedia('(hover: hover)') to
detect, pointerenter/leave to toggle a hovering flag, pointerdown/up
for drag, and a tiny lerp on requestAnimationFrame so the return to
center feels smooth. Eyebrow text now reads 'Drag or hover to
compare' to signal both modes.
Also drop text-align: center on .skill-demo-eyebrow and .skill-demo-caption
for the same left-align consistency.
Paul BakausandClaude Opus 4.7