Docs / ${escapeHtml(categoryLabel)}
${titleHtml}
${escapeHtml(tagline)}
${metaStrip}
${bodyHtml}
Reference${escapeHtml(title)}
${refBody}
Deeper reference
${refs}Pairs with ${rel.pairs}
`;
} else if (rel.leadsTo?.length) {
const links = rel.leadsTo.map((c) => `${c}`).join(', ');
metaHtml = `Leads to ${links}
`;
} else if (rel.combinesWith?.length) {
const links = rel.combinesWith.map((c) => `${c}`).join(', ');
metaHtml = `Combines with ${links}
`;
}
// Row is a (not an ) so the inner relationship links are valid.
// The name on the left is the primary link target.
return `
`;
};
// Render category sections, skipping the Create category's /impeccable root
// (shown as a hero card above) but keeping everything else in place.
let categoriesHtml = '';
for (const category of CATEGORY_ORDER) {
const list = (skillsByCategory[category] || []).filter((s) => s.id !== 'impeccable');
if (list.length === 0) continue;
const rowsHtml = list.map(renderCommandRow).join('');
categoriesHtml += `
${list.length} ${list.length === 1 ? 'command' : 'commands'}
`;
}
return `
`;
}
/**
* Wrap sidebar + main content in the docs-browser layout shell.
*/
function wrapInDocsLayout(sidebarHtml, mainHtml) {
return `
${escapeHtml(section)} `;
})
.join('\n');
return `
`;
}
/**
* Render one rule card inside the anti-patterns main column.
*/
function renderRuleCard(rule) {
const categoryLabel = rule.category === 'slop' ? 'AI slop' : 'Quality';
const layer = rule.layer || 'cli';
const layerLabel = LAYER_LABELS[layer] || layer;
const layerTitle = LAYER_DESCRIPTIONS[layer] || '';
const skillLink = rule.skillSection
? `See in /impeccable`
: '';
const visual = rule.visual
? ``
: '';
return `
${visual}
`;
}
function escapeAttr(str) {
return String(str || '').replace(/"/g, '"');
}
/**
* Render the /tutorials index main content.
*/
function renderTutorialsIndexMain(tutorials) {
const cards = tutorials
.map(
(t) => `
${String(t.order).padStart(2, '0')}
→
`,
)
.join('\n');
return `
`;
}
/**
* Render the /visual-mode page main content.
*
* Single-column layout, no sidebar. Editorial header, live iframe embed
* of the detector running on a synthetic slop page, three-card section
* explaining the invocation methods, then a grid of real specimens the
* user can click into to see the overlay on a different page.
*/
function renderVisualModeMain() {
const specimenCards = GALLERY_ITEMS.map(
(item) => `
`,
).join('\n');
return `
`;
}
/**
* Render a tutorial detail page main content.
*/
function renderTutorialDetail(tutorial, knownSkillIds) {
const bodyHtml = renderMarkdown(tutorial.body, { knownSkillIds });
return `
${bodyHtml}
`;
}
/**
* Render the /anti-patterns main column content.
*/
function renderAntiPatternsMain(grouped, totalRules) {
let sectionsHtml = '';
for (const section of grouped.order) {
const rules = grouped.bySection[section] || [];
if (rules.length === 0) continue;
const slug = slugify(section);
sectionsHtml += `
`;
}
const detectedCount = grouped.order
.flatMap((s) => grouped.bySection[s] || [])
.filter((r) => r.layer !== 'llm').length;
const llmCount = totalRules - detectedCount;
return `
`;
}
/**
* Entry point. Generates all sub-page HTML files.
*
* @param {string} rootDir
* @returns {Promise<{ files: string[] }>} list of generated file paths (absolute)
*/
export async function generateSubPages(rootDir) {
const data = await buildSubPageData(rootDir);
const outDirs = {
docs: path.join(rootDir, 'public/docs'),
antiPatterns: path.join(rootDir, 'public/anti-patterns'),
tutorials: path.join(rootDir, 'public/tutorials'),
visualMode: path.join(rootDir, 'public/visual-mode'),
};
// Fresh output dirs each time so stale files don't linger.
for (const dir of Object.values(outDirs)) {
if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
fs.mkdirSync(dir, { recursive: true });
}
const generated = [];
// Docs index: the full command reference with rich cards.
{
const sidebar = renderDocsSidebar(data.skillsByCategory, data.tutorials, null);
const main = renderSkillsOverviewMain(data.skillsByCategory, data.skills);
const html = renderPage({
title: 'Docs | Impeccable',
description:
'22 commands that teach your AI harness how to design. Browse by category: create, evaluate, refine, simplify, harden.',
bodyHtml: wrapInDocsLayout(sidebar, main),
activeNav: 'docs',
canonicalPath: '/docs',
bodyClass: 'sub-page skills-layout-page',
});
const out = path.join(outDirs.docs, 'index.html');
fs.writeFileSync(out, html, 'utf-8');
generated.push(out);
}
// Per-command detail pages: same docs-browser shell as the overview.
for (const skill of data.skills) {
const sidebar = renderDocsSidebar(data.skillsByCategory, data.tutorials, { kind: 'skill', id: skill.id });
const main = renderSkillDetail(skill, data.knownSkillIds);
const title = skill.isSubCommand
? `/impeccable ${skill.id} | Impeccable`
: `/${skill.id} | Impeccable`;
const description = skill.editorial?.frontmatter?.tagline || skill.description;
const html = renderPage({
title,
description,
bodyHtml: wrapInDocsLayout(sidebar, main),
activeNav: 'docs',
canonicalPath: `/docs/${skill.id}`,
bodyClass: 'sub-page skills-layout-page',
});
const out = path.join(outDirs.docs, `${skill.id}.html`);
fs.writeFileSync(out, html, 'utf-8');
generated.push(out);
}
// Anti-patterns index: single page, docs-browser shell with TOC sidebar.
{
const grouped = groupRulesBySection(data.rules);
const sidebar = renderAntiPatternsSidebar(grouped);
const main = renderAntiPatternsMain(grouped, data.rules.length);
const html = renderPage({
title: 'Anti-patterns | Impeccable',
description: `${data.rules.length} deterministic detection rules that flag the visible tells of AI-generated interfaces and common quality issues. Used by npx impeccable detect and the browser extension.`,
bodyHtml: wrapInDocsLayout(sidebar, main),
activeNav: 'anti-patterns',
canonicalPath: '/anti-patterns',
bodyClass: 'sub-page skills-layout-page anti-patterns-page',
});
const out = path.join(outDirs.antiPatterns, 'index.html');
fs.writeFileSync(out, html, 'utf-8');
generated.push(out);
}
// Tutorials index (under the unified Docs umbrella).
if (data.tutorials.length > 0) {
const sidebar = renderDocsSidebar(data.skillsByCategory, data.tutorials, null);
const main = renderTutorialsIndexMain(data.tutorials);
const html = renderPage({
title: 'Tutorials | Impeccable',
description: `${data.tutorials.length} short, opinionated walk-throughs of the highest-leverage Impeccable workflows.`,
bodyHtml: wrapInDocsLayout(sidebar, main),
activeNav: 'docs',
canonicalPath: '/tutorials',
bodyClass: 'sub-page skills-layout-page tutorials-page',
});
const out = path.join(outDirs.tutorials, 'index.html');
fs.writeFileSync(out, html, 'utf-8');
generated.push(out);
}
// Visual Mode: single standalone page, no sidebar, single-column layout.
{
const html = renderPage({
title: 'Visual Mode | Impeccable',
description:
'See every anti-pattern flagged directly on the page. Live detection overlay from Impeccable, available via /impeccable critique, npx impeccable live, or the upcoming Chrome extension.',
bodyHtml: renderVisualModeMain(),
activeNav: 'visual-mode',
canonicalPath: '/visual-mode',
bodyClass: 'sub-page visual-mode-page-body',
});
const out = path.join(outDirs.visualMode, 'index.html');
fs.writeFileSync(out, html, 'utf-8');
generated.push(out);
}
// Tutorial detail pages.
for (const tutorial of data.tutorials) {
const sidebar = renderDocsSidebar(data.skillsByCategory, data.tutorials, { kind: 'tutorial', slug: tutorial.slug });
const main = renderTutorialDetail(tutorial, data.knownSkillIds);
const html = renderPage({
title: `${tutorial.title} | Tutorials | Impeccable`,
description: tutorial.description || tutorial.tagline || '',
bodyHtml: wrapInDocsLayout(sidebar, main),
activeNav: 'docs',
canonicalPath: `/tutorials/${tutorial.slug}`,
bodyClass: 'sub-page skills-layout-page tutorials-page',
});
const out = path.join(outDirs.tutorials, `${tutorial.slug}.html`);
fs.writeFileSync(out, html, 'utf-8');
generated.push(out);
}
return { files: generated };
}
/impeccable ${escapeHtml(skill.id)}${isBeta ? ' BETA' : ''}
${escapeHtml(shortTagline)}
${metaHtml}${escapeHtml(CATEGORY_LABELS[category])}
${escapeHtml(CATEGORY_DESCRIPTIONS[category])}
${rowsHtml}
1 skill · ${commandCount} commands
Commands
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:
${categoriesHtml}
${sidebarHtml}
`;
}
/**
* 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 anti-patterns sidebar: a table of contents of rule sections
* with per-section rule counts. Every entry anchor-jumps to the section
* in the main column.
*/
function renderAntiPatternsSidebar(grouped) {
const entries = grouped.order
.filter((section) => grouped.bySection[section]?.length > 0)
.map((section) => {
const slug = slugify(section);
const count = grouped.bySection[section].length;
return `
${mainHtml}
${categoryLabel}
${escapeHtml(layerLabel)}
${escapeHtml(rule.name)}
${escapeHtml(rule.description)}
${skillLink}${escapeHtml(t.title)}
${escapeHtml(t.tagline || t.description)}
${tutorials.length} walk-throughs
Tutorials
Short, opinionated walk-throughs of the highest-leverage workflows. Each one takes around ten minutes and ends with something working in your project.
${cards}
${escapeHtml(item.title)}
${escapeHtml(item.desc)}
Live detection overlay
Visual Mode
See every anti-pattern flagged directly on the page. No screenshots, no JSON to map back to line numbers. The overlay draws an outline and a label on every element the detector catches, so you fix them in place.
Live on a synthetic slop page
Hover or tap any outlined element to see which rule fired.
Three ways to run it
Inside /impeccable critique
/impeccable critique
The design review command opens the overlay automatically during its browser assessment pass. You get the 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.
Easiest
Chrome extension
One-click activation on any tab. Install from Chrome Web Store →
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 scroll around and hover the outlined elements.
${specimenCards}
Tutorials / ${String(tutorial.order).padStart(2, '0')}
${escapeHtml(tutorial.title)}
${tutorial.tagline ? `${escapeHtml(tutorial.tagline)}
` : ''}${escapeHtml(section)}
${rules.length} ${rules.length === 1 ? 'rule' : 'rules'}
${rules.map(renderRuleCard).join('\n')}
${totalRules} rules
Anti-patterns
The full catalog of patterns /impeccable teaches against. ${detectedCount} are caught by a deterministic detector (npx impeccable detect or the browser extension). ${llmCount} can only be flagged by /impeccable critique's LLM review pass. Want to see them live on real pages? Try Visual Mode.
How to read this
AI slop rules flag the visible tells of AI-generated UIs. Quality rules flag general design mistakes that are not AI-specific but still hurt the work. Each rule also shows how it is detected:
- CLI
- Deterministic. Runs from
npx impeccable detecton 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.
${sectionsHtml}