/**
* Generate static HTML files for /docs, /slop, /tutorials, /live-mode,
* /designing.
*
* Called from both scripts/build.js (before buildStaticSite) and
* server/index.js (at module load), so dev and prod share the same
* code path and output shape.
*
* Output lives under public/docs/, public/slop/, public/tutorials/, all
* gitignored. Bun's HTML loader picks them up the same way it picks up
* the hand-authored pages.
*/
import fs from 'node:fs';
import path from 'node:path';
import {
buildSubPageData,
CATEGORY_ORDER,
CATEGORY_LABELS,
CATEGORY_DESCRIPTIONS,
COMMAND_RELATIONSHIPS,
LAYER_LABELS,
LAYER_DESCRIPTIONS,
GALLERY_ITEMS,
} from './lib/sub-pages-data.js';
import { renderMarkdown, slugify } from './lib/render-markdown.js';
import { renderPage } from './lib/render-page.js';
function escapeHtml(str) {
return String(str || '')
.replace(/&/g, '&')
.replace(//g, '>')
.replace(/"/g, '"')
.replace(/'/g, ''');
}
/**
* Render the before/after split-compare demo block for a skill.
* Returns '' when the skill has no demo data (e.g. /shape).
*/
function renderSkillDemo(skill) {
if (!skill.demo) return '';
const { before, after, caption } = skill.demo;
return `
`;
const hasDemo = demoHtml.trim().length > 0;
// Sub-commands are accessed via /impeccable . Show "/impeccable" as
// a smaller namespace label above the command name, matching the magazine
// spread treatment so the command name stays at full display size.
const titleHtml = skill.isSubCommand
? `/impeccable${escapeHtml(skill.id)}`
: `/${escapeHtml(skill.id)}`;
return `
${editorialHtml ? `\n${editorialHtml}\n` : ''}
${caseCalloutHtml}
${skill.isSubCommand ? 'reference/' + escapeHtml(skill.id) + '.md' : 'SKILL.md'}${skill.isSubCommand ? 'Loaded when the impeccable skill routes to this command.' : 'The canonical skill definition your AI harness loads.'}
${bodyHtml}
${referencesHtml}
`;
}
/**
* Render the unified Docs sidebar used across /skills and /tutorials.
* Shows every skill grouped by category, then tutorials as a final
* group. Pass the current page identifier so we can mark it:
*
* { kind: 'skill', id: 'polish' }
* { kind: 'tutorial', slug: 'getting-started' }
* null (no current page)
*/
function renderDocsSidebar(skillsByCategory, tutorials, current = null) {
// Label the toggle button with the current page so mobile users know
// where they are at a glance, then open the menu to switch.
let currentLabel = 'Docs menu';
if (current?.kind === 'skill') {
currentLabel = `/${current.id}`;
} else if (current?.kind === 'tutorial') {
const t = tutorials.find((x) => x.slug === current.slug);
if (t) currentLabel = t.title;
}
let html = `
`;
return html;
}
/**
* Render the /skills overview main column content (not the sidebar).
* This is the orientation piece: what skills are, how to pick one,
* the six categories explained with inline cross-links to detail pages.
*/
function renderSkillsOverviewMain(skillsByCategory, allSkills) {
// Build a lookup by id so we can pull taglines/descriptions for the cards.
const skillsById = Object.fromEntries(allSkills.map((s) => [s.id, s]));
const commandCount = allSkills.filter((s) => s.id !== 'impeccable').length;
// Short, clean tagline for the home command card. Fall back to the editorial
// tagline if set, otherwise use a default.
const impeccable = skillsById['impeccable'];
const homeTagline = impeccable?.editorial?.frontmatter?.tagline
|| 'The design intelligence behind every command.';
// Render a single command as a compact row: name on the left, description
// and relationship on the right. Matches the original cheatsheet density.
const renderCommandRow = (skill) => {
const tagline = skill.editorial?.frontmatter?.tagline || skill.description;
const shortTagline = tagline.length > 140 ? tagline.slice(0, 137) + '...' : tagline;
const rel = COMMAND_RELATIONSHIPS[skill.id] || {};
const isAlpha = skill.id === 'live';
let metaHtml = '';
if (rel.pairs) {
metaHtml = `
Impeccable gives you a shared design vocabulary with your AI. ${commandCount} commands that each encode a specific design discipline, so you can steer with precision. Pick one for the job or let the skill route you automatically.
The home command
/impeccable
${escapeHtml(homeTagline)}
Call /impeccable directly for freeform design work with the full guidebook loaded. Or reach for one of its specialized modes:
`;
}
/**
* Wrap sidebar + main content in the docs-browser layout shell.
*/
function wrapInDocsLayout(sidebarHtml, mainHtml) {
return `
${sidebarHtml}
${mainHtml}
`;
}
/**
* Group anti-pattern rules by skill section.
* Rules without a skillSection fall into a 'General quality' bucket.
*/
function groupRulesBySection(rules) {
// Canonical ordering. Additional sections referenced by rules (e.g.
// 'Interaction', 'Responsive' from LLM-only entries) are appended to
// the end, before 'General quality', so every rule renders.
const primaryOrder = [
'Visual Details',
'Typography',
'Color & Contrast',
'Layout & Space',
'Motion',
'Interaction',
'Responsive',
];
const bySection = {};
for (const name of primaryOrder) bySection[name] = [];
bySection['General quality'] = [];
for (const rule of rules) {
const section = rule.skillSection || 'General quality';
if (!bySection[section]) bySection[section] = [];
bySection[section].push(rule);
}
// Sort each bucket: slop first (they're the named tells), then quality.
for (const name of Object.keys(bySection)) {
bySection[name].sort((a, b) => {
if (a.category !== b.category) return a.category === 'slop' ? -1 : 1;
return a.name.localeCompare(b.name);
});
}
// Final render order: primary sections first, then any extras that
// rules introduced, then General quality last.
const order = [...primaryOrder];
for (const name of Object.keys(bySection)) {
if (!order.includes(name) && name !== 'General quality') {
order.push(name);
}
}
order.push('General quality');
return { order, bySection };
}
/**
* Render the /slop sidebar: a table of contents for the four top-level
* sections (See it / Try it live / The catalog / Run it yourself), with
* the catalog's per-section anchors nested under "The catalog".
*/
function renderSlopSidebar(grouped, gallerySize) {
const catalogEntries = grouped.order
.filter((section) => grouped.bySection[section]?.length > 0)
.map((section) => {
const slug = slugify(section);
const count = grouped.bySection[section].length;
return `
Short, opinionated walk-throughs of the highest-leverage workflows. Each one takes around ten minutes and ends with something working in your project.
${cards}
`;
}
/**
* Render the /slop page main content.
*
* Four numbered sections in one scroll: See it (iframe overlay demo),
* Try it live (specimen gallery), The catalog (the full rule list), and
* Run it yourself (three invocation methods). Lives inside the docs
* layout shell so the slop sidebar (renderSlopSidebar) navigates both
* the top-level anchors and the per-catalog-section anchors.
*/
function renderSlopMain(grouped, totalRules) {
// Catalog: rule-card sections, grouped by skillSection.
let catalogSectionsHtml = '';
for (const section of grouped.order) {
const rules = grouped.bySection[section] || [];
if (rules.length === 0) continue;
const slug = slugify(section);
catalogSectionsHtml += `
${totalRules} patterns that mark an interface as AI-generated, and the detection overlay that catches them in place. Watch it flag them live, try it on ${GALLERY_ITEMS.length} synthetic specimens, or browse the full catalog. ${detectedCount} rules run deterministically (npx impeccable detect or the browser extension); ${llmCount} need /impeccable critique's LLM review pass.
01 See it
Live on a synthetic slop page
Hover or tap any outlined element to see which rule fired.
02 Try it live
These ${GALLERY_ITEMS.length} synthetic slop pages ship with the detector script baked in. Click any to see the overlay running on a real page, then hover the outlined elements.
${specimenCards}
03 The catalog
Every pattern /impeccable teaches against. AI slop rules flag the tells of AI-generated UIs; Quality rules flag general design mistakes that hurt regardless of who wrote them.
How to read this
Each rule shows how it is detected:
CLI
Deterministic. Runs from npx impeccable detect on files, no browser required.
Browser
Deterministic, but needs real browser layout. Runs via the browser extension or Puppeteer, not the plain CLI.
LLM only
No deterministic detector. Caught by /impeccable critique during its LLM design review.
The design review command opens the overlay automatically during its browser assessment pass. Deterministic findings highlighted in place while the LLM runs its separate heuristic review.
Standalone CLI
npx impeccable live
Starts a local server that serves the detector script. Inject it into any page via a <script> tag to see the overlay. Works on your own dev server, a staging URL, or anyone's live page.
`;
}
/**
* Render the animated Live Mode demo block. HTML structure matches the
* homepage #live-demo exactly so public/js/components/live-demo.js can
* drive it without modification. The CSS (.live-demo-*) lives in
* public/css/live-mode.css, imported by main.css and also loaded on this
* page via extraHead.
*/
function renderLiveModeDemo() {
return `
localhost:3000
Newsletter
Subscribe for updates
Monthly-ish design notes.
No. 04
Letters, occasionally.
A postcard from the editor, about once a month. No tracking pixels, no "just checking in."
☞
Dispatch
Design notes, every other Thursday.
☆☆☆
Field Notes
A monthly letter, for people who still read email for pleasure.
more playful
Generating variants…
1 / 3
Variant 3 written to source
/
`;
}
/**
* Render the /live-mode page main content.
*
* Marketing-style single-column layout mirroring /visual-mode's structure.
* Surfaces the animated homepage live-demo, a three-stage narrative,
* pathway cards (tutorial / reference / install), and the supported
* framework strip.
*/
function renderLiveModeMain() {
return `
New in v3.0 Alpha
Live Mode
Pick any element in the browser. Drop a comment or a stroke. Three production-quality variants swap in via your framework's HMR. Accept the one you want and it writes back to source.
Why alpha: Live Mode works end-to-end and is ready to try, but it still needs more testing against real-world repos and framework configs. Expect rough edges on uncommon setups, and please report what breaks.
$/impeccable live
${renderLiveModeDemo()}
Click the frame or scroll it into view to start the loop. Respects prefers-reduced-motion.
What happens, in three moves
01 · Pick
Point at what bugs you
Click any element on your running dev server. Add a comment pin where the issue lives. Draw a stroke through the bit you want to change. Or just type "more playful".
Newsletter card
1
02 · Generate
Three genuinely different takes
Variants anchor to different archetypes, not three riffs on color. Each one explores a different primary axis: hierarchy, typography, density, layout, or palette strategy.
No.04
Dispatch
Field
03 · Accept
Lands in real source
The accepted variant replaces the picked element in your source file. CSS consolidates into your real stylesheet, not inline. Discard all three and the original stays.
`;
}
/**
/**
* Render the /designing page.
*
* Editorial orientation: four-phase loop (start → iterate → polish →
* maintain) as the spine, plus three appendix sections (register,
* interop, avoid) and a CTA climax. Cards are rare: most sections
* rely on typography, hairline rules, and whitespace for structure.
*/
function renderDesigningMain() {
const loopNodes = [
{ id: 'start', num: '01', name: 'Start', hint: 'From a blank file, through a brief, to a designed feature.' },
{ id: 'iterate', num: '02', name: 'Iterate', hint: 'Refine in place. Command line or in the browser.' },
{ id: 'polish', num: '03', name: 'Polish', hint: 'The pre-ship gauntlet. Audit, clarify, harden.' },
{ id: 'maintain', num: '04', name: 'Maintain', hint: 'Pay down design debt before it solidifies.' },
];
const nodeHtml = loopNodes.map((n) => `
${n.num}${n.name}${escapeHtml(n.hint)}`).join('');
return `
The core loop
Designing with Impeccable
Shipping a real interface is a loop. Four phases, each with one place to begin.
The core loop
${nodeHtml}
↘↙↖↗
designingimpeccable
01 · Start
From a blank file to a designed feature.
Three commands, one arc. /impeccable teach writes the brief, once per project. /impeccable shape drafts a reference you can look at. /impeccable craft codes toward what you can see. Words, then pictures, then code.
Teach runs a short discovery interview about audience, register, voice, and anti-references. It writes PRODUCT.md and, if there's code to scan, a DESIGN.md. Every later command reads both files before generating.
shape + craft · in pictures
Since image generation crossed the reference-quality threshold, shape can draft a brand toolkit you review at a glance, and craft can code toward a hi-fi mock instead of a paragraph. Neo Mirai is the full loop: generated direction, implemented page, browser iteration.
Shape
Brand toolkit. Identity, palette, type, icon language, applications, social tiles, UI direction. One plate, reviewable at a glance. Approved decisions get written into DESIGN.md.
Visualize
Hi-fi reference. The destination, before the first line of CSS. Craft codes toward a concrete image, not an abstract brief. That is the step change.
Ship
Live build. The mock became semantic markup, regenerated assets, responsive fixes, nav state, speaker carousel behavior, and browser-verified polish. Open the live site.
The first two plates were generated by OpenAI GPT Image 2. The third is the implemented Neo Mirai page. Gemini Nano Banana Pro, Imagen 4 Ultra, and Grok Imagen work the same way, via Codex, Gemini CLI, and compatible harnesses.
02 · Iterate
Refine what's there.
Once something exists, you're iterating. There are two paths: specific commands for named dimensions, or Live Mode for visual exploration.
Command line
When the edit has a name.
Type a command and let the skill encode a specific discipline. Best when you know the word: typography, layout, color, motion.
$/impeccable polish pricing
$/impeccable bolder hero
$/impeccable typeset checkout
Live Mode
When the edit is easier to point at.
Pick any element in the browser, draw, type, hit Go. Three production-quality variants. Accept one and it writes to source.
Scans tokens, components, and rendered output. Writes a spec-compliant DESIGN.md.
Two lanes
Brand, or product.
Two defaults with different vocabularies. Impeccable picks the lane from your task cue and PRODUCT.md before every command, so typeset, animate, colorize, and friends adjust their output to match. You rarely need to set it by hand.
Brand
Design IS the product. Marketing, landing, editorial, long-form, portfolio.
No. 04 · DispatchLetters, occasionally.
Product
Design serves the task. App UI, admin, dashboards, tools.
An anti-patterns list, for using the anti-patterns tool.
×
Running both Impeccable and Anthropic's frontend-design skill
Anthropic still promotes their skill in Claude Code, but it's been unmaintained and is now behind on recommended patterns. Run both and they collide on vocabulary, cancelling each other out. Pick one.
×
Pinning every command
Pinning brings back /audit, /polish, /critique as shortcuts. Pin everything and you've re-exploded the / menu the v3.0 consolidation cleaned up. Pin the two or three you reach for daily.
×
Skipping teach
Commands still run without PRODUCT.md and DESIGN.md. They default to generic SaaS patterns. The floor is meaningfully higher with context. Run teach once; every later command benefits.
×
Treating it like a linter
Impeccable is an opinionated design partner, not a validator. It has a point of view. Push back with a reason and it'll work with you. Ignore the opinion without a reason and output gets worse, not better.
`;
}
/**
* Render a tutorial detail page main content.
*/
function renderTutorialDetail(tutorial, knownSkillIds) {
const bodyHtml = renderMarkdown(tutorial.body, { knownSkillIds });
return `
