skills/pbakaus_impeccable
1
0
Fork 0
mirror of https://github.com/pbakaus/impeccable.git synced 2026-09-14 23:26:39 +03:00
Code Issues Packages Projects Releases Wiki Activity
643 Commits 96 Branches 69 Tags
ccf3573579ffcda14bf43ed32c83a34a1cb45900
Commit Graph
30 Commits
Author SHA1 Message Date
Paul BakausGitHubClaude Opus 4.7
 		b8f09c8142 Migrate site from Bun to Astro (#130) 
* feat(site): scaffold Astro migration, convert 3 pages

Phase 1+2 of the Astro migration:

- Astro v6.2.1 installed, srcDir: 'site', static output to build/
- Shared layout: Base.astro (head, fonts, meta, slots), Header.astro
  (star count in one place: 23k), Footer.astro
- CSS moved from public/css/ to site/styles/ (9 files, @import chains
  resolve via Vite)
- Three pages converted: privacy, cases/neo-mirai, live-mode
  (all return 200 on astro dev)

Remaining: designing, slop, homepage, content collections (docs),
JS migration, server/index.js deletion, build.js cleanup.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(site): migrate all 6 main pages to Astro

Converts the remaining pages:
- designing/index.html → site/pages/designing/index.astro (551 lines)
- slop/index.html → site/pages/slop/index.astro (909 lines)
- index.html → site/pages/index.astro (1278 lines, the homepage)

Base.astro gains OG meta tag props, before-header/after-header
slots (for grain overlay and section nav), and configurable mainId.

Homepage uses link tags to public/css/ instead of frontmatter CSS
imports to avoid esbuild choking on :has() in main.css. Curly
braces inside <code> elements (CSS snippets in changelog) escaped
with HTML entities to prevent Astro JSX expression parsing.

All 6 pages return 200 on astro dev. Branch: feat/astro-migration.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(site): content collections for docs and tutorials

Replaces the 1532-line build-sub-pages.js generator with Astro v6
content collections:

- 24 skill editorial files move to site/content/skills/
- 4 tutorial files move to site/content/tutorials/
- site/content.config.ts defines both collections with glob loaders
- site/pages/docs/[...slug].astro reads skills collection + command
  metadata from source/skills/ at build time
- site/pages/docs/index.astro renders the command grid grouped by
  category (create, evaluate, refine, simplify, harden, system)
- site/pages/tutorials/ mirrors the pattern with ordered index
- Doc.astro layout provides sidebar nav, breadcrumbs, and related-
  command chips from the COMMAND_RELATIONSHIPS data
- Category/relationship data extracted to site/data/sub-pages-data.ts

All 15 tested pages return 200: 6 main pages + 5 docs + 2 tutorials
+ 2 index pages. The old generator is not yet deleted (Task #6).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(site): move JS source from public/js/ to site/scripts/

Moves all 49 JS files (app.js + 48 in js/) into site/scripts/.
Vite now processes them through its module bundler instead of
serving them raw from public/.

app.js import paths updated from ./js/X to ./X (the js/ nesting
is gone since app.js now lives alongside the subdirectories).

Homepage and live-mode page switch from <script is:inline src="/app.js">
to Vite-processed <script> imports, so tree-shaking, bundling,
and minification happen automatically at build time.

public/js/ still exists for now (cleanup in Task #6) and the
generated/counts.js build output path needs updating there too.
@paper-design/shaders added to npm dependencies (was missing).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor(site): delete old Bun server, generator, and duplicated files

Cleanup after the Astro migration:

Deleted:
- server/index.js (233 lines, replaced by `astro dev`)
- scripts/build-sub-pages.js (1532 lines, replaced by content collections)
- scripts/lib/render-page.js (247 lines, replaced by Base.astro layout)
- content/site/partials/header.html (replaced by Header.astro component)
- public/index.html, privacy.html, designing/, live-mode/, cases/
  (replaced by .astro pages in site/pages/)
- public/css/ (moved to site/styles/)
- public/js/ old source files (moved to site/scripts/)
- public/app.js (moved to site/scripts/app.js)

Kept in public/:
- antipattern-examples/ (standalone HTML demos, not Astro pages)
- antipattern-images/, assets/, neo-mirai/ (static assets)
- js/detect-antipatterns-browser.js (referenced by antipattern examples)
- js/generated/counts.js (build output from scripts/build.js)
- _data/api/ (generated API data, now written to public/ so Astro
  passes it through to build/)

Updated:
- astro.config.mjs: added redirects (skills->docs, cheatsheet->docs,
  gallery->slop, neon-mirai->neo-mirai, etc.)
- package.json: dev->astro dev, build->build:skills+build:site,
  preview->astro preview
- scripts/build.js: removed buildStaticSite(), generateSubPages(),
  static-asset copying. API data writes to public/_data/ instead of
  build/_data/. Site-header validator is a no-op (shared component).
  Em-dash validator scans site/components + site/layouts, not pages
  (pages contain content from other sources like detector descriptions).
- .gitignore: removed public/slop/ entry

Tests: 186/186 pass. Skills build: clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(site): fix redirect config for Astro compatibility

Move the dynamic /skills/:id -> /docs/:id redirect to public/_redirects
(Cloudflare Pages native format) since Astro's redirect config can't
handle dynamic routes that don't match existing page patterns.

Remove duplicate trailing-slash redirect entries that caused warnings.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(site): switch remaining pages from /css/ link tags to frontmatter imports

Doc.astro, docs/index, tutorials/index, and tutorials/[slug] were
still using <link href="/css/sub-pages.css"> which pointed at the
deleted public/css/ directory. Switched to frontmatter CSS imports
(import '../../styles/sub-pages.css') which Vite resolves from
site/styles/.

Homepage also switches from link tags to frontmatter imports for
main.css and sub-pages.css — the esbuild error that originally
forced the link-tag workaround was caused by unescaped curly braces
in the HTML content (since fixed), not by the CSS itself.

All pages verified visually in Chrome: homepage hero, foundation
grid, docs index (card grid with categories), docs detail (sidebar +
editorial content + visual mockups), designing (core loop diagram),
privacy, tutorials. Header renders with 23k stars on every page.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(site): fix edge-to-edge sections, broken API paths, CSS links

Three fixes:

1. Homepage sections sat on the viewport edge because Base.astro's
   <main> lacked the site-content class (provides max-width + padding).
   Added mainClass prop to Base.astro; homepage sets mainClass="site-content".

2. "Failed to load commands" because app.js fetched /api/commands
   which only existed in the old Bun server's routing. Updated to
   fetch from /_data/api/commands.json (the static JSON files that
   build:skills writes to public/_data/).

3. CSS reference fix (previous commit was incomplete): Doc.astro,
   docs/index, tutorials pages all used <link href="/css/sub-pages.css">
   pointing at deleted public/css/. Switched to frontmatter imports.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(site): add sidebar to docs index page

The docs index was using Base.astro directly without the skills-layout
grid, so it rendered without a sidebar. Added the same sidebar structure
from Doc.astro (category-grouped command list) and wrapped the content
in the skills-layout grid.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(site): extract footer CSS to shared file, import in Base.astro

Footer was unstyled on sub-pages because footer CSS lived only in
main.css (loaded by the homepage) not in sub-pages.css. Extracted
the 95 lines of footer rules into site/styles/footer.css and
imported it in Base.astro so every page gets footer styles regardless
of which page-specific CSS it loads.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(demos): move landing-demo into repo, add as slop specimens

Moves ~/code/landing-demo/ into demos/landing-demo/ (without
node_modules or the redundant .claude/.agents skill copies — the
repo root's skill is found by walking up). PRODUCT.md, DESIGN.md,
DESIGN.json, PROMPT.md, and SCRIPT.md stay in place so running
Claude from demos/landing-demo/ picks up the project context.

Also copies both pages as slop specimens to public/antipattern-examples/
with the detector script baked in:
- new-slop-2026.html (Fraunces + warm cream editorial monoculture)
- old-slop-2022.html (purple gradient + glassmorphism + neon glow)

These can be linked from the slop page gallery alongside the
existing 11 synthetic specimens.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(slop): replace single demo iframe with Then vs Now comparison

The "See it" section (01) on the slop page now shows two side-by-side
browser frames: 2022 slop (purple gradients, glassmorphism, neon glow)
and 2026 slop (Fraunces, warm cream, editorial restraint). Both run
the detector overlay live — hover either to see which rules fire.

Replaces the single visual-mode-demo.html iframe. Responsive: stacks
vertically on viewports below 900px.

Caption: "Same engine, different decade, both flagged."

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(slop): switch to single-frame era toggle, center the section

Replaces the side-by-side dual-iframe layout with a single large
frame and a segmented 2022/2026 toggle. Clicking the toggle swaps
which iframe is visible (both pre-loaded, instant switch). Browser
chrome title updates to match the active era.

Centers the lede text and toggle above the frame for visual
cohesion with the full-width iframe below.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(slop): left-align See It section, toggle inline with lede

Moves the era toggle to the right of the lede paragraph using a
flex row (align-items: flex-end). Left-aligned text + right-docked
toggle matches the rest of the page's flow instead of standing out
as a centered island. Stacks vertically on narrow viewports.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(slop): left-align iframe, remove max-width and auto margin

The visual-mode-preview had max-width: 1040px + margin: 0 auto
which centered it within the column. Override both in the
.slop-then-now context so the frame fills the full content width
flush with the text above. Caption left-aligned to match.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(site): update star count to 24k (24,062)

One file, one edit. The Astro migration working as intended.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(build): regenerate pnpm-lock.yaml for astro + shaders deps

Cloudflare Pages uses pnpm with frozen-lockfile. The lockfile was
stale after adding astro, @astrojs/cloudflare, and
@paper-design/shaders via npm.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(build): resolve 3 bugbot review issues

1. Restore public/slop/ to .gitignore — prevents accidental legacy
   generator output from conflicting with the Astro page.

2. Move astro and @paper-design/shaders to devDependencies — these
   are site-build tools, not CLI runtime deps. Removes @astrojs/cloudflare
   entirely (unused; static output mode needs no adapter).

3. Fix Astro wiping build:skills output — CF config (_headers,
   _redirects, _routes.json) and API data now write to public/ so
   Astro copies them through. Dist ZIPs copy to build/_data/dist/
   as a post-build step (after Astro finishes).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(build): merge duplicate devDependencies, use npx for astro CLI

The previous commit created a second devDependencies key in
package.json. JSON doesn't support duplicate keys — pnpm ignored
the first block (with astro), so `astro build` wasn't found.

Merged astro and @paper-design/shaders into the existing
devDependencies block. Changed `astro build/dev/preview` to
`npx astro build/dev/preview` so pnpm finds the local binary
on Cloudflare Pages (which doesn't add node_modules/.bin to PATH
by default).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(demos): remove private demo script and prompt from public repo

SCRIPT.md contained a detailed conference talk script with personal
delivery strategies, rehearsed Q&A answers, and venue details.
PROMPT.md contained the origin brief for the demo page. Neither
belongs in a public repo.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(build): gitignore generated public/ artifacts, consolidate redirects

1. Generated files written to public/ by build:skills (API data,
   CF config, browser detector, counts.js) are now gitignored.
   Prevents noisy diffs and merge conflicts from committed build
   artifacts.

2. Removed duplicate redirects from astro.config.mjs. All redirects
   now live in one place: the _redirects file generated by
   scripts/build.js (which Cloudflare Pages processes natively).
   Eliminates the dual-maintenance risk where the two sources
   could drift apart.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-02 11:29:10 -07:00
Paul BakausandClaude Opus 4.7 a312da5ec7 fix(site): update GitHub star count to 23k, add changelog highlight reel 
Star count was 21k on sub-pages and the header partial, 22k on the
homepage. Updated all seven source files to 23k (actual: 23,692).

Changelog section gains a curated "Highlights since v3.0" block
above the full version history, which now collapses behind a
disclosure toggle. Fixes the vertical bloat from 9 entries in
three weeks while keeping v3.0's anchor content visible.

Also fixes a nesting bug where an orphan </div> from the old
changelog-list wrapper prematurely closed the changelog-section,
breaking the two-column changelog+FAQ grid layout.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-30 09:44:28 -07:00
Paul BakausandClaude Opus 4.7 e0ab3a73b7 feat(live + site): preserve variant attr on accept, designing-page redesigns 
Runtime fix in live-browser.js: the 2s static-server fallback in handleAccept
now swaps the outer wrapper with the `[data-impeccable-variant="N"]` div itself
(+ display:contents), matching what live-accept.mjs writes to disk. Scope rules
anchored on the variant attribute keep matching on the non-HMR path, so the
accepted design no longer flashes unstyled until reload. Propagated to all
harness script copies.

/designing:
- §03 Polish redesigned as drenched magenta masthead: commands live in the band,
  three title/description columns beneath on cream.
- §04 Maintain redesigned as architectural poster diptych: extract + document
  vizzes become the hero element, caption below.
- §05 Interop section removed.
- §05 (was §06) "Pick a register" renamed to "Brand, or product." with a
  two-lane hairline-divided layout and an auto-selected framing in the sub.

Live mode status: BETA → ALPHA across the periodic table, magazine spread,
and docs callout, reflecting real-world-testing readiness.

Skill bootstrap: removed the `<post-update-cleanup>` block from source/SKILL.md
(the source repo is the origin; running cleanup-deprecated here would touch
legitimate source). CLAUDE.md and AGENTS.md now document the skip.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-23 16:44:46 -07:00
Paul BakausandClaude Opus 4.7 5316809139 feat(site): merge /anti-patterns and /visual-mode into /slop 
Top nav was at six items and growing. The anti-patterns catalog and the
visual-mode overlay demo were always two views of the same subject (the
rule set and seeing it caught in place), so collapsing them into one page
reduces nav weight and puts the catalog + live demo next to each other.

Four sections in one scroll: See it (iframe demo), Try it live (specimen
gallery), The catalog (full rule list), Run it yourself (invocation
methods). Sidebar TOC nests the catalog sections under "The catalog" for
deep linking. 301s from the old URLs preserve external links.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-23 13:13:56 -07:00
Paul BakausandClaude Opus 4.7 a95212aa87 feat(site): Designing orientation page with compass loop 
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>
 2026-04-23 09:13:15 -07:00
Paul BakausandClaude Opus 4.7 3ffc485a8d refine(site): "The Case" crossfade + content cleanup, pattern-tabs scroll 
- 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>
 2026-04-22 18:47:33 -07:00
Paul BakausandClaude Opus 4.7 2341fe3637 feat(live): tune popover, theme-aware bar/picker, action icons, params system 
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>
 2026-04-22 18:17:17 -07:00
Paul Bakaus 549f92577c feat(site): v3.0 changelog expansion, pin FAQ, stale-ref cleanup 
- v3.0 changelog now covers 6 items (was 2): Live Mode, PRODUCT.md,
  DESIGN.md (with Google Stitch spec compliance), brand/product
  registers, plus the existing consolidation + pin/unpin.
- New FAQ entry answering "how do I get /critique back" via pinning.
- Added Pin commands back as shortcuts section to /docs/impeccable
  editorial so it's findable outside the FAQ.
- Reduced changelog item font size (0.9375rem) to match length.
- Swept user-facing copy: .impeccable.md -> PRODUCT.md, removed three
  stale npx impeccable live references (the CLI subcommand no longer
  exists; live is /impeccable live inside the skill).
- Historical v1.5.0 changelog entry preserved as-is (period-accurate).
 2026-04-22 11:28:19 -07:00
Paul BakausandClaude Opus 4.6 e58cbc432f Split /onboard back out as its own command (21 commands total) 
Pre-3.0, onboard was folded into /harden when we were trying to reduce
namespace pollution. In the single-skill model that tradeoff is gone,
so the weakest of the old merges is the first to undo.

Harden and onboard live in different mental modes. Harden is defensive
(edge cases, i18n, overflow, errors). Onboard is activation (first-run
flows, empty states as CTAs, progressive disclosure). A user thinking
"design the onboarding flow" was never going to type /impeccable harden.

Changes:
- New reference file at source/skills/impeccable/reference/onboard.md,
  restored from the pre-merge version in git history rather than the
  condensed 33-line summary that was in harden.md.
- Removed the "Onboarding & First-Run Experience" section from
  source/skills/impeccable/reference/harden.md.
- Updated harden description/editorial/process-steps to drop onboarding
  keywords; split commandProcessSteps so harden stays focused on
  production resilience and onboard gets its own phases.
- Registered onboard in: SKILL.md description + command menu + router
  table, command-metadata.json, IMPECCABLE_SUB_COMMANDS, pin.mjs
  VALID_COMMANDS, SKILL_CATEGORIES, COMMAND_RELATIONSHIPS, data.js
  commandCategories + commandProcessSteps + commandRelationships,
  framework-viz commandSymbols + commandNumbers.
- Reused the existing content/site/skills/onboard.md editorial wrapper
  (it was orphaned by the merge but never deleted), updating it to use
  /impeccable onboard.
- Bumped all user-facing count references 20 -> 21: public/index.html,
  CLAUDE.md, README.md, NOTICE.md, plugin.json, marketplace.json,
  sitemap.xml, build-sub-pages.js.
- Harness dir audit.md and critique.md changes are the
  {{available_commands}} placeholder expanding to include onboard.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-11 19:21:45 -07:00
Paul BakausandClaude Opus 4.6 b0f44f83c6 Consolidate 18 skills into 1 /impeccable skill with 20 commands 
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>
 2026-04-10 19:45:17 -07:00
Paul BakausandClaude Opus 4.6 2af435d2a5 Update GitHub star count from 17k to 18k 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-10 10:42:44 -07:00
Paul BakausandClaude Opus 4.6 faa7453db7 Consolidate skills from 21 to 18: rename, merge, and fold 
- Rename /arrange to /layout for clarity
- Merge /normalize into /polish (design system discovery + cleanup phases)
- Merge /onboard into /harden (onboarding, empty states, progressive disclosure)
- Fold /extract into /impeccable extract sub-mode (reference file, sidebar link)
- Update all counts, cross-references, data files, demos, and metadata
- Remove System category (now empty)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-09 20:39:02 -07:00
Paul BakausandClaude Opus 4.6 0567d1954d Fix scroll anchors for /impeccable craft and /impeccable teach 
Use h3 headings with custom IDs instead of inline spans so the browser
scrolls to the right position. Added {#id} syntax support to the
markdown heading renderer.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-09 16:48:22 -07:00
Paul BakausandClaude Opus 4.6 e94fe3d931 Merge Syne-specific anti-pattern into the general overused fonts list 
Syne stays in reflex_fonts_to_reject but no longer gets a standalone
DON'T rule in the skill or a separate LLM-only entry in the catalog.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-09 16:46:33 -07:00
Paul BakausandClaude Opus 4.6 a024195ddb Fix website copy: shape/craft relationship, install sections, tutorial accuracy 
- Clarify that /impeccable craft runs /shape internally (not the other way around)
- Add three-mode documentation (freeform/craft/teach) to /impeccable page with anchor links
- Add sidebar sub-links for /impeccable craft and /impeccable teach
- Fix hallucinated npx impeccable live description in tutorial and visual-mode page
- Remove nonsensical "Do not skip the independent part" from critique tutorial
- Make Step 4 less prescriptive (users can fix all at once or one-by-one)
- Improve CLI and browser extension install copy with specific features and use cases

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-09 16:39:45 -07:00
Paul BakausandClaude Opus 4.6 0e4cc16620 Update Chrome extension from 'coming soon' to published 
Extension is now live on the Chrome Web Store. Replace all
coming-soon placeholders with install links on the homepage,
visual-mode page, and overlay tutorial.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-09 08:59:26 -07:00
Paul Bakaus 27d1b13bc2 New /visual-mode top-level page, pull gallery out of /anti-patterns 
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.
 2026-04-08 13:04:23 -07:00
Paul Bakaus ebe07cbae5 Merge gallery into /anti-patterns, hide rule ids 
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.
 2026-04-08 12:48:24 -07:00
Paul Bakaus c384e6b568 Anti-patterns page polish: visuals for LLM rules, wider grid, compact legend, sidebar divider fix 
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.
 2026-04-08 12:38:12 -07:00
Paul Bakaus 0d87b5afb5 Overhaul /anti-patterns with visuals, detection layers, and LLM rules 
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.
 2026-04-08 12:05:12 -07:00
Paul Bakaus feea28058f Trim fabricated installer output from getting-started tutorial 
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.
 2026-04-08 10:58:38 -07:00
Paul Bakaus eb130c4af9 Copy buttons on code blocks + merge Skills and Tutorials under Docs 
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.
 2026-04-08 10:50:23 -07:00
Paul Bakaus a89f7f5040 Polish pass on editorial wrappers and skill detail layout 
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.
 2026-04-08 10:26:01 -07:00
Paul Bakaus 500fe448cd Generate /tutorials index + 2 walk-throughs 
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).
 2026-04-08 10:18:04 -07:00
Paul Bakaus 71a909f7da Editorial wrappers for the remaining 7 skills 
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).
 2026-04-08 10:11:06 -07:00
Paul Bakaus 4b3cdede1b Editorial wrappers for 7 refine-category skills 
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).
 2026-04-08 10:07:30 -07:00
Paul Bakaus 2592db4c80 Editorial wrappers for 7 core skills 
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.
 2026-04-08 10:03:58 -07:00
Paul Bakaus 80d7502737 Extend docs-browser shell to detail pages, tighten sidebar, ban em dashes 
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 &mdash; 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.
 2026-04-08 09:45:13 -07:00
Paul Bakaus c4dc0feb23 Polish the site header based on user feedback 
- 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)
 2026-04-08 09:03:13 -07:00
Paul Bakaus 54b687d16f Add sub-page render pipeline foundation 
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.
 2026-04-08 08:01:34 -07:00