Drop the metric-heavy framing and lead with the user-facing wins
(font/color diversity, design quality, Codex support) plus a brief
nod to the eval framework and anti-attractor technique.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tightened the v2.0 changelog on the homepage. Same information density,
fewer words, no em dashes, and dropped what does not concern users.
- Skill rewrite bullet: same numbers, shorter framing.
- Detection engine bullet: dropped the 'hard-to-hit cases that slip
past regex-only scanners' flourish at the end.
- CLI bullet: collapsed parenthetical clauses into short phrases.
- Chrome extension bullet: replaced the em dash with a colon.
- /critique bullet: tightened.
- /shape bullet: replaced the em dash with a period break.
- "Rebuilt site and docs" renamed to "New docs site" and trimmed to
just what users experience (top-level sections, skill pages,
tutorials, rule cards). Dropped the 'mobile experience overhauled'
line — implementation detail, not a user-facing feature.
- Licensing bullet: renamed to 'Apache 2.0 throughout'.
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.
Replaces the brand-only card with a split layout: wordmark left,
floating Chrome extension detection panel right. Generator now counts
user-invocable, non-deprecated skills from source/skills/ (v2.0 unified
structure) instead of the removed source/commands/ directory.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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.
Expands the v2.0 entry from 5 flat bullets to 9 grouped highlights
and surfaces the additions the existing entry missed: the data-driven
skill rewrite (validated against the internal eval framework with
concrete per-niche metrics), the Chrome DevTools extension, the
rebuilt site and docs, /critique's persona sub-agents, Rovo Dev
support, and Apache 2.0 unification. Each item leads with a bold
label so the list stays scannable despite the length.
Hero version link tightened to signal the three most visible pieces
of the release (detection engine, Chrome extension, data-driven
skill) instead of just the detector.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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.
jsdom's CSSOM silently drops any border shorthand containing var(),
leaving the computed style empty — which hid the canonical real-world
side-tab pattern (border-left: Npx solid var(--brand)) from the Node
detector path. Real browsers resolve var() natively, so this only
affected the jsdom path.
Add a pre-pass that walks the stylesheets, reads border shorthands off
rule.style (jsdom preserves them there even when it drops them from
cssText), resolves var() against :root custom properties via the
documentElement's computed style, and attaches the result to a per-
element override map. checkElementBorders consults the map whenever
jsdom returned an empty width, or substitutes a resolved color when
jsdom kept a literal var() string. Hex and named colors are normalized
to rgb() so isNeutralColor can classify them correctly — without that,
--line:#e5e7eb slipped through as non-neutral.
Adds four flag cases and three pass cases to modern-color-borders.html
covering shorthand, mixed neutral+colored, border-right, card-shaped
label, neutral-resolving var, thin var, and uniform all-sides var.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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.
Adds an Evals Framework section pointing future Claude sessions at
evals/AGENT.md (the comprehensive private guide) and inlines the
highest-leverage facts: primary baseline model is gpt-5.4 medium
reasoning, n=20 standard sample size, do not use Haiku as primary
target, always smoke test before sweep.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The skill's "don't use Inter / don't use dark / don't center" negatives
were creating new attractors (the model picks Fraunces / light / grid
instead, every time). Inline always-applicable principles into SKILL.md,
add a font selection anti-attractor procedure that forces the model to
enumerate AND reject its reflex defaults, switch high-stakes blocks to
XML structure, tighten side-tab and gradient-text bans to specific CSS
patterns, ban Syne explicitly, and strip named font/color prescriptions
from the references. Validated against the internal eval framework on
Qwen 3.6 Plus across 7 niches: Fraunces dropped from 92% to 0% on kids
reading, side-tabs from 76% to 20% on vintage moto, no theme regressions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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).
Recognize "DO NOT" / "DO" lines (with optional colon) inside <rules>
and <absolute_bans> blocks, and make skillGuideline substring matching
case-insensitive so the validator handles the new XML-structured
SKILL.md without rejecting the refactored prose.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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.
The tutorial showed a hallucinated "installer output" block with
specific ✓-prefixed lines that do not match what npx skills add
actually prints. Delete the block and collapse the surrounding prose
into a single sentence that describes what the command does without
promising specific output. The important guidance (auto-detect, which
directories, reload the harness, look for slash commands) is preserved.
The tutorial h1 used font-style: italic + weight 500, which read as
cursive and sat oddly next to the non-italic h1 on /skills, /anti-patterns,
and skill detail pages. Align it with the shared .sub-page-title
treatment: display serif at weight 400, no italic, clamp(2.5rem, 6vw,
4.5rem). The italic style stays on subsection headings (skill category
titles, anti-pattern section titles) where it still reads as a label,
not a page title.
Two changes bundled:
1. Before/after split demos on every skill detail page.
- loadCommandDemos() in sub-pages-data.js: dynamically imports each
module in public/js/demos/commands (the same files the homepage
uses), returning a { skillId: { id, caption, before, after } } map.
Falls back to a warn-and-continue if a demo file can't be loaded
so one bad demo doesn't break the whole generator.
- buildSubPageData becomes async; caller in build-sub-pages.js
awaits it.
- Each skill object gets a .demo field (may be null for /shape).
- renderSkillDemo() produces the .split-comparison markup matching
the homepage: .split-container with .split-before + .split-after
+ .split-divider, plus Before/After labels and the caption. The
block sits between the detail header and the editorial wrapper
so readers see the visual before reading any prose.
- sub-pages.css ports the core .split-* layout from main.css (the
.slop-* and .impeccable-* helpers are homepage-specific and not
copied). Height is 360px to match the docs column.
- render-page.js grows a lightweight inline split-compare init
script (60 lines of vanilla JS) that handles drag and the skewed
clip-path without depending on the homepage's full lerp/ResizeObserver
module. Runs only on pages that actually have .split-container.
2. Sidebar reorder: Tutorials first, then skills.
Walk-throughs are the on-ramp; they belong at the top of the sidebar
where a new visitor will find them. Add <hr class="skills-sidebar-divider">
between the Tutorials group and the first skill category so the two
sections read as distinct.
Verified: /skills/polish, /skills/bolder, /skills/critique all render
the demo block. /skills/shape correctly has none. Sidebar on any /skills
or /tutorials page shows Tutorials first, then a thin mist divider,
then Create / Evaluate / Refine / Simplify / Harden / System skill
categories.
Two small-to-medium improvements bundled together.
1. Copy buttons on every rendered code block.
- render-markdown.js: wrap each fenced code block in a .code-block-wrap
container and emit a <button class="code-block-copy" data-copy="...">
alongside it. Button text is set via CSS ::before content so the
'Copy' / 'Copied' label is a single toggle class (.is-copied).
- render-page.js: 12-line inline script at the end of the body wires
a delegated click handler that calls navigator.clipboard.writeText
and flips .is-copied for 1.5s.
- sub-pages.css: button styles matching the dark terminal palette,
hidden until you hover the code block, accent-colored success state.
2. Merge Skills and Tutorials under a single Docs nav item.
- Rename the Skills nav link to 'Docs' in every header (partial +
4 hand-authored pages). Drop the separate Tutorials nav item; it
now lives inside Docs. Anti-patterns stays as its own top-level.
- scripts/build-sub-pages.js: replace renderSkillsSidebar and
renderTutorialsSidebar with a unified renderDocsSidebar that shows
every skill category followed by a Tutorials group. Takes a
current descriptor of shape { kind: 'skill'|'tutorial', id|slug }
so both skill detail and tutorial detail pages can mark the active
row. activeNav on every /skills/* and /tutorials/* page is now
'docs'; the shared site header's data-nav matches.
Verified: /skills/polish and /tutorials/getting-started both render
with the unified Docs sidebar (all 21 skills grouped by category +
both tutorials as a final group). The Docs nav item is aria-current
on both. Copy buttons appear on every fenced code block and toggle
to 'Copied' when clicked.
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.
Sitemap previously listed only the landing page. Extend it to include
every canonical URL shipped in this IA expansion:
- 4 hand-authored pages (/, /cheatsheet, /gallery, /privacy)
- 3 section indexes (/skills, /anti-patterns, /tutorials)
- 21 skill detail pages (/skills/{id})
- 2 tutorial detail pages (/tutorials/getting-started, /tutorials/critique-with-overlay)
Priority ladder:
1.0 landing
0.9 section indexes
0.8 detail pages
0.7 utility pages (cheatsheet, gallery)
Note: privacy is intentionally not indexed (noindex meta) so it stays
out of the sitemap.
Smoke-tested all 31 live routes (29 pages + sitemap.xml + robots, not
the 2 that are noindex): all return 200.
Third and final new section. Adds the tutorials browser with two
hand-written walk-throughs: "Getting started" and "Critique with the
visual overlay". Same docs-browser shell as skills and anti-patterns.
- content/site/tutorials/getting-started.md
Five-minute install, teach, and first polish pass. Covers npx skills
add, answering the teach interview honestly, and running /polish on
an existing page. Includes common issues and what to try next.
- content/site/tutorials/critique-with-overlay.md
Ten-minute walk-through of the full /critique workflow with the
browser overlay. Covers the two-assessment model (LLM + detector),
the three ways to open the overlay (extension, inside critique, or
standalone via `npx impeccable live`), the fix-reload-verify loop,
and how to interpret merged reports.
- scripts/build-sub-pages.js
- renderTutorialsSidebar(): tutorial list with current-item marking
- renderTutorialsIndexMain(): card grid with mono order numbers,
italic display titles, taglines, arrow affordances
- renderTutorialDetail(): breadcrumb eyebrow, italic display title,
plain tagline, rendered markdown body inside .prose
- Wire both into the main generator loop.
- sub-pages-data.js already reads content/site/tutorials/*.md and
sorts by frontmatter.order, so no data-layer change was needed.
- public/css/sub-pages.css
- .tutorial-card grid (number, body, arrow) with hover border
darken + arrow slide. Mono order numbers, italic display titles.
- .tutorial-detail header with italic display title and plain sans
tagline (matching the visual rhythm of skill detail pages without
the mono command style since tutorials are prose, not commands).
Add the anti-patterns browser. Single page, same docs-browser shell as
the skills section, but the sidebar is a table of contents instead of
a navigation list.
- scripts/build-sub-pages.js
- groupRulesBySection(): bucket the 25 detection rules by skill
section (Visual Details, Typography, Color & Contrast, Layout &
Space, Motion) plus a 'General quality' bucket for the 7 rules
without a skillSection cross-reference. Each bucket sorts slop
rules first, then quality rules alphabetically.
- renderAntiPatternsSidebar(): TOC with anchor links to each
section, per-section rule count on the right, reusing the
.skills-sidebar styles with anti-patterns-specific tweaks for
the two-column item layout.
- renderRuleCard(): rule id + category badge + name + description
+ optional 'See in /impeccable' link that jumps to the right
anchor on the skill detail page.
- renderAntiPatternsMain(): editorial header ('25 detection rules')
+ 'How to read this' legend callout + six sections each with a
grid of rule cards.
- Wire the new page into the main generator loop.
- public/css/sub-pages.css
- .rule-card grid (auto-fill minmax 320px) with header row, mono
rule id, pill category badge, bold name, body description,
arrow skill link at the bottom.
- .rule-card-category variants: slop uses accent-dim background
with accent text, quality uses mist background with charcoal text.
- Section headers with baseline-aligned title and right-aligned
rule count, matching the rhythm of the /skills overview.
- Anti-patterns sidebar count styling (tabular-nums, ash).
Verified: /anti-patterns returns 200 with 25 rule cards rendered across
all six section anchors.
Final batch. Every user-invocable skill now has a hand-written editorial
wrapper. 21 of 21 done.
- clarify: rewrite confusing UX copy so interfaces explain themselves
- adapt: make designs work across screens and contexts without amputation
- normalize: pull drifted UI back into the design system
- optimize: diagnose and fix UI performance from LCP to bundle size
- onboard: first-run experiences, empty states, and paths to value
- overdrive: push interfaces past conventional limits (shaders, physics)
- extract: pull reusable components, tokens, and patterns into the system
Every wrapper follows the four-section template, keeps taglines tight,
and names the neighboring skill when the user is reaching for the wrong
tool (clarify -> delight when the copy is already clear, adapt -> harden
when responsive reveals edge cases, extract -> wait when the pattern
has fewer than three usages).
Second batch. Covers the seven skills that improve existing interfaces
along a single dimension at a time.
- typeset: fix generic typography (fonts, hierarchy, scale, readability)
- arrange: fix layout, spacing, and visual rhythm
- colorize: add strategic color to monochrome interfaces without slop
- animate: purposeful motion that conveys state, never decoration
- delight: small personality moments that turn functional into memorable
- bolder: push safe designs toward impact without sliding into loud
- quieter: tone down overstimulating designs while keeping their intent
Each wrapper keeps the four-section template (When to use it / How it
works / Try it / Pitfalls), stays concrete, flags the neighboring skill
when the user is reaching for the wrong tool, and calls out the explicit
anti-patterns each skill refuses to produce (bounces for animate, extra
colors for colorize, decoration for the rest).
First batch of hand-written editorial wrappers. Each wrapper lives at
content/site/skills/{id}.md and renders above the auto-generated SKILL.md
body on the skill detail page.
Shape follows the standard four-section template: When to use it / How
it works / Try it / Pitfalls. Plus a tagline in frontmatter that the
page template uses in place of the bare frontmatter description.
Shipped:
- impeccable: the foundation skill, why it exists, and when to call teach
- critique: the two-assessment design review with heuristic scoring
- audit: five-dimension technical quality check with P0-P3 severities
- polish: the meticulous final pass, what it covers, when not to run it
- shape: discovery interview that produces a design brief
- distill: ruthless subtraction, when it helps vs when to reach for arrange
- harden: edge cases, i18n, error states, production readiness
Tone: direct, opinionated, no hedging, no em dashes, concrete try-it
examples with expected output shapes. Next 14 wrappers ship in batches
2 and 3.
Three tightening passes based on visual feedback.
- Sidebar alignment. The skills layout now uses the same horizontal
padding clamp as the site header, so the sidebar column's left edge
sits under the brand logo above. Sidebar items drop their 10px left
padding and sit flush with the column edge; the 2px active-item
accent lives in a -2px margin so it hangs in the layout gutter
without pushing text right. Drop the max-width constraint so the
docs shell extends wall-to-wall on wide screens like a real docs site.
- Sidebar font. The command list was 0.8125rem which read too small
next to the sidebar group titles. Bump to 0.875rem and tighten the
vertical rhythm (4px vs 3px padding, group title margin-bottom 6px).
- Skill detail title. The title was set in mono at ~3rem and the
tagline in italic display, which inverted the visual weight (the
tagline felt heavier than the title). Rework to match the landing
page's .spread-command-name palette styling:
- Title: display serif, clamp(3rem, 5.5vw, 5rem), line-height 0.95
- Leading '/' split into <span class="skill-detail-title-slash">
and colored with --color-accent at weight 300 so it reads as a
quiet prefix glyph
- Tagline: body sans at 1-1.125rem, no italics, max-width 60ch
Builds on the /skills overview landing. Every skill detail page now lives
inside the same sticky-sidebar shell, with the active skill marked via
aria-current and pulled out of the list with a 2px accent border.
- scripts/build-sub-pages.js: detail pages now wrap the .skill-detail
body in wrapInDocsLayout() and pass currentSkillId into the sidebar
renderer so the active row is marked
- public/css/sub-pages.css sidebar pass:
- Narrow from 260px to 200px (was way too wide for the content)
- Drop the redundant "Skills" label at the top (it was visually
competing with the category titles); keep the node for a11y via
visually-hidden styling
- Group titles shrink to 0.625rem mono uppercase in --color-ash so
they read as quiet signposts, not headings
- Tighten item line-height to 1.5 and vertical padding to 3px
- Replace the box-shadow inset accent with a border-left accent on
the active item, leaving it visually pulled left
- Simplify .skill-detail sizing so it works inside .skills-main
without its own max-width / padding
- Ban em dashes in user-facing copy everywhere:
- Rewrite 9 copy lines in index.html, 2 title tags in gallery.html,
inline category descriptions, the /skills overview lede + how-to,
two skills-generator comments, one aria-label, and the page titles
for Skills and skill detail pages
- New validateNoEmDashes step in scripts/build.js scans content/site,
public/*.html, and the sub-page generator sources. Build fails on
any — or — in user-facing copy. Uses commas, colons, periods,
or parentheses instead
Build green: all 26 HTML entrypoints bundle cleanly, all four hand-authored
pages retain the shared site header, anti-pattern rules still match
SKILL.md, zero em dashes.
The old /skills was one long scrollable list. Replace it with a proper
app-shell layout: sticky left sidebar with every skill grouped by
category, main column on the right with an orientation piece (intro
+ 'how to pick one' callout + category sections with chip lists).
- scripts/build-sub-pages.js
- renderSkillsSidebar(): the sticky left rail used across the /skills
section. Takes an optional currentSkillId so we can mark the active
skill with aria-current when detail pages adopt the same shell in a
later commit
- renderSkillsOverviewMain(): the right column. Editorial header,
'how to pick one' callout that inlines 5 hot-link skill references,
then one block per category (title, count, description, chip row
of all skills in that category)
- wrapInDocsLayout(): tiny helper that pastes the sidebar and main
into a .skills-layout grid
- public/css/sub-pages.css
- Copy .skip-link a11y styles over from main.css so the 'Skip to
content' link is properly hidden until keyboard focus (was showing
unstyled at the top-left of every generated page)
- Add .skills-layout grid shell (260px sidebar + flex main column,
max-width 1400px, clamp-based horizontal padding)
- Add sticky .skills-sidebar with its own scroll-y overflow and a
thin scrollbar; group titles + mono link list; aria-current styling
with a 2px left accent bar
- Add .skills-overview-howto callout, category sections with chip
rows, and mobile collapse (sidebar becomes an inline block above
the main column at <=920px)
- Introduce --site-header-height and --skills-sidebar-width tokens
No detail page layout changes in this commit — those still use the
single-column .skill-detail shell.
Ships the first new sub-page section. Every user-invocable skill now has
its own page at /skills/{id}, with the canonical SKILL.md body rendered
via marked. The index at /skills lists all 21 skills grouped by category.
Editorial wrappers are opt-in: if content/site/skills/{id}.md exists, it
renders above the canonical body (with a "The skill itself" divider).
All 21 pages currently ship with the auto-rendered body only; hand-written
wrappers land in the next few commits.
- scripts/lib/sub-pages-data.js: builds the data model. Reuses
readSourceFiles() from lib/utils.js for skill content; parses the
ANTIPATTERNS array out of src/detect-antipatterns.mjs; reads optional
editorial wrappers from content/site/skills/*.md; validates that every
user-invocable skill has a category entry (build fails loudly if not).
- scripts/build-sub-pages.js: orchestrator. Writes generated HTML into
public/skills/*.html (gitignored). Called from both scripts/build.js
(before buildStaticSite) and server/index.js (at module load) so dev
and prod share the same generation code path.
- scripts/lib/render-page.js: new assetDepth parameter so generated
pages one level deep under public/ use relative paths (../favicon.svg,
../css/sub-pages.css) that Bun's HTML loader can resolve on disk.
- scripts/build.js: pass generated files into Bun.build entrypoints;
post-process to flatten build/public/* → build/* (Bun preserves the
public/ prefix when entrypoints span multiple depths).
- server/index.js: generateSubPages() runs at module load; new routes
/skills, /skills/:id, /anti-patterns, /tutorials, /tutorials/:slug
serve the pre-generated files via Bun.file().
- public/css/sub-pages.css: adds sub-page layout shell, skills index
grouped-list styling, skill detail header/meta chips/divider, collapsed
<details> reference sections, and a .prose block for rendered markdown
with editorial typography, code blocks, and inline code.
Verified: bun run build produces 26 HTML files (4 hand-authored + 22
generated), all flat under build/. Dev server returns 200 on /skills,
/skills/polish, /skills/impeccable, /skills/critique. Tests pass.
- Kill double underlines on nav items and brand: scope '.site-header a
{ text-decoration: none }' more specifically so the page-level 'a'
rule in main.css can't bleed through
- Add an inline SVG logo mark next to the 'Impeccable' wordmark (reuses
the favicon.svg glyph, inlined so Bun's HTML loader doesn't try to
bundle '/favicon.svg' from a non-relative path)
- Add a subtle GitHub star pill (icon + 17k + small star) at the far
right of the header; replaces the bare 'GitHub' nav text link
- Remove the duplicate .github-link floater from the hero on the landing
page; the header pill is the single place for the stars signal now
- Mobile: stop nav items from wrapping mid-word; lower the breakpoint
to 820px; enable horizontal scroll with a mask fade on the right;
hide the 'Home' link on mobile (the brand is already the home link);
hide the brand wordmark below 480px (logo glyph alone); hide the 17k
label inside the github pill on mobile (keep the icon + star)
The Visual Details DON'T entry in source/skills/impeccable/SKILL.md
was rewritten to cover border-left/border-right specifically ('colored
accent stripe') and no longer contains the old 'thick colored border
on one side' substring. Update the side-tab and border-accent-on-rounded
rules so the build-time validator passes again.
- Regenerate src/detect-antipatterns-browser.js via bun run build:browser
Every hand-authored HTML page now carries the same sticky top nav:
Home / Skills / Anti-Patterns / Tutorials / Gallery / GitHub. The three
future sections (skills, anti-patterns, tutorials) will land behind
these links in subsequent commits.
- Add <header class="site-header"> with a <!-- site-header v1 --> marker
to index, cheatsheet, gallery, privacy
- Each page links public/css/sub-pages.css so it picks up the shared
header styling (sticky, backdrop blur, accent-underlined current item)
- Gallery: drop the inline .site-header/.header-brand/.header-nav
definitions that predate the shared component (class names conflicted)
- Cheatsheet: restructure the page title into .cheatsheet-page-header
so it doesn't collide with the new <header class="site-header">; move
the page container max-width/padding off <body> onto .cheatsheet-page-header,
main, and footer so the shared sticky header spans the full viewport
- Privacy: full styling refresh using sub-pages.css tokens + a small
inline block for the page body typography
- Add a validateSiteHeader step to scripts/build.js that fails the build
if any of the four pages drops the marker
- Add /privacy route to server/index.js so extensionless URLs work
All four built pages pass the marker check; dev server serves all four
with 200 and the shared header.
Groundwork for new /skills, /anti-patterns, /tutorials sections.
No user-visible changes yet — this is pure plumbing.
- Split main.css into tokens.css (design tokens + reset, ~100 lines) and
main.css (everything else, imports tokens.css). Lets sub-pages import
only tokens without pulling in the landing-page component CSS.
- Add marked as a dependency.
- Add scripts/lib/render-markdown.js: marked wrapper with a custom link
resolver (skill slugs, reference/*.md anchors, external rel=noopener),
stable heading slugger, and terminal-style code blocks.
- Add scripts/lib/render-page.js: page shell wrapper that injects the
shared site header partial with aria-current marking.
- Add content/site/partials/header.html: shared site header with nav
(Home / Skills / Anti-Patterns / Tutorials / Gallery / GitHub).
- Add public/css/sub-pages.css: shared styles for generated pages, with
.site-header styling (sticky, backdrop blur, accent-underlined active
nav item) and mobile collapse.
Build still produces the same 104 KB landing-page CSS chunk; tests pass.
Tailwind was wired into the build but the project didn't actually use it:
no @tailwind/@theme/@apply directives in source CSS, no utility classes
in any HTML or JS, no tailwindcss dependency in package.json, and no
HTML page linked to the compiled styles.css output.
Bun's HTML loader already handles main.css's @import chain transparently
in both `bun run dev` and `bun run build`. Removing the Tailwind step:
- Deletes buildTailwindCSS() from scripts/build.js (and the now-unused
execSync import)
- Removes public/css/styles.css (dead compiled output that nothing read)
- Updates CLAUDE.md to drop the "must rebuild Tailwind after CSS edits"
instruction
Verified: `bun run build` produces the same 104 KB CSS chunk linked from
index.html via Bun's HTML loader. No more rebuild step after CSS edits.
- Fix isNeutralColor to handle oklch, oklab, lch, lab, hsl, and hwb
with format-specific chroma/saturation thresholds. jsdom returns
these formats literally, so the previous rgb-only regex caused every
modern-format border color to be silently treated as neutral and
skipped by checkBorders.
- Flip the unknown-format fallback from neutral to colored, so
unrecognized color strings err on the side of detection.
- Introduce a narrower BORDER_SAFE_TAGS set (SAFE_TAGS minus 'label')
used only by the border checks. Card-shaped clickable labels with
thick colored side borders are now detected, while colors, motion,
and nested-card checks continue to skip labels to avoid false
positives on real form labels.
- Add tests/fixtures/antipatterns/modern-color-borders.html with 8
flag cases (oklch x3, oklab, lch, lab, plus 2 label cards) and
10 pass cases (neutrals across formats, plain inline labels,
thin/neutral-bordered labels, colored-on-all-sides).
Reproducer (preop-portal demo): side-tab findings rise from 0 to 12.
- Restructure install section into a split primary card with the
recommended path on the left and other install methods on the right
- Drop the prefix toggle UI; bundle name is now baked into data-bundle
- Balance the Stay updated step as paired Substack iframe + X follow card
with matching height, border, and treatment
- Pair Changelog and FAQ side-by-side on desktop with a centered divider
and shared border-top; section nav highlights both when in view
- Tone down the Visual Mode demo by removing side-tab borders, stacked
card icons, and tiny body text so the overlay reads cleanly
- Refine the Chrome extension callout: drop the pill badge, use an
editorial eyebrow above the title, enlarge the thumbnail
- Exclude private evals/ directory from version control
The Visual Mode section had three competing cards in the right column
(25 deterministic checks, Three ways to use it, Get the Chrome extension)
all wrapped in bordered/backgrounded containers. The live detection
overlay iframe on the left is the visual anchor for the section — the
right column should be quieter editorial blocks, not three cards
fighting for attention.
Layout changes
- Strip card chrome from .visual-mode-feature: no padding, background,
or border-radius. Just an eyebrow label + paragraph in editorial flow.
- Strip card chrome from .detection-callout: no padding, background,
border, border-radius, or hover-transform theatrics.
- Bump .visual-mode-details gap from spacing-md to spacing-xl so the
three blocks breathe with editorial space instead of feeling stacked.
- Bump body text from 0.8125rem to 0.9375rem for readability without
the card padding.
Extension callout
- Add extension-detection.png — a tight 600×508 crop of the Chrome
extension's DevTools panel showing detected anti-patterns ("AI color
palette", "Overused font", "Quality issues", "Low contrast text").
Reads at thumbnail size and clearly shows the extension UI in action.
- Whole callout is a single anchor (entire row clickable).
- 88×88 image thumbnail on the left with a subtle border that shifts
to accent on hover.
- NEW eyebrow stacked above the "Get the Chrome extension →" CTA, both
left-aligned next to the thumbnail.
The result: the iframe carries the visual weight, the right column
becomes a quiet editorial sidebar, and the extension CTA gets just
enough visual punch (the thumbnail) without competing with the demo.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Emojis render as multicolor glyphs regardless of CSS \`color\`, so the
text color is irrelevant for contrast calculations. The detector was
flagging emoji icons as low-contrast whenever the surrounding bg/text
colors were close (e.g. an emoji card with text-color set to match
the bg). Adds an isEmojiOnlyText() helper that returns true when the
direct text consists entirely of emoji characters (and zero-width
joiners, variation selectors, skin-tone modifiers, regional
indicators), and skips both gray-on-color and low-contrast checks
when it's true.
Same insight fixes a missed icon-tile-stack detection: many AI-
generated cards use \`<div class="card-icon">⚡</div>\` where the
tile contains the emoji directly as text, not an <svg>/<i> child.
The detector now also recognizes these "inline emoji icon" tiles.
Both fixes are TDD'd: new test cases in color.html (two emoji cards
with matching text/bg colors) and icon-tile-stack.html (the inline
emoji tile pattern). The test suite went from green → red → green
across both rules.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Paul BakausandClaude Opus 4.6