html-style-router

name

html-style-router

description

Route any standalone HTML deliverable to the correct design system BEFORE writing markup. Reads document intent and picks one of 10 genre skills (warm-academic / Economist / McKinsey / Bloomberg / Hermes-TUI + 5 visual-poster genres), all composing on the shared typography foundation. Use when: producing ANY report, document, dashboard, poster, cover, card, figure, or briefing as HTML. Trigger: html report / 生成HTML / 网页报告 / 做个报告 / dashboard / 海报 / 封面 / 知识卡片 / whitepaper / strategy deck / 研究简报 / style this / 风格路由 / which design system. NOT for: React component logic, inline HTML snippets, or PPT decks (that is a slides router).

---

name: html-style-router description: "Trigger FIRST before writing any standalone HTML file. Routes to correct design-system skill based on document type (report, whitepaper, guide, proposal, briefing, analysis, poster). NOT for inline HTML snippets or React components." combo-tags: [daily-book-reading, html-rendering]

HTML Style Router

Automatic style routing for standalone HTML document deliverables. Detects document type and dispatches to the correct design system.

When to Trigger

This skill activates when generating ANY standalone HTML document deliverable. It runs BEFORE writing HTML, to determine which style skill to follow.

Trigger keywords: HTML, document, report, whitepaper, guide, proposal, briefing, analysis, kickoff, poster, research, due diligence, assessment, landscape.

Gotchas

1. This skill must run BEFORE writing any HTML. If you write HTML first and then route, you've already committed to a style. The router's job is to CHOOSE the style before any code is generated. Violating this order means rewriting the entire file.

2. When in doubt between Economist and McKinsey, check the verb. ANALYZE/ARGUE/COMPARE → Economist. RECOMMEND/STRATEGIZE/DECIDE → McKinsey. The distinction is "describing what is" vs "prescribing what to do."

3. All HTML deliverables must produce 2 files per the 2份制 rule. English .md (for agents) + Chinese .html (for humans, with style routing). Don't produce 4 files (en+zh x md+html). The .html version is always Chinese and always styled.

4. Footer format is non-negotiable. Centered, #9B9B9D color, 13px, line-height 2.2, no "Author:" prefix. Just: [ProjectName] v[X.Y] — [Document Type] + Your Name | [e-mail] + generation date.

5. After generating HTML, always open it in the browser. User's explicit requirement since 2026-03-09. No exceptions.

6. Filesystem / taxonomy / route-map sections are not code blocks. If a section is explaining information architecture, directory structure, route map, or capability taxonomy, do not use one giant dark pre block as the primary visual. Lead with grouped domains, cards, pillars, or a role/ownership table; keep the raw tree only as appendix/evidence.

7. Manual subsection insertion can introduce stray </div> that cascades layout — render-validate every insert. When adding a new subsection (e.g. §4.6) into an existing legacy HTML using the <div class="container"> > <div class="section"> frame pattern, it is easy to add one extra </div> thinking it closes a nested helper div, when it actually closes the parent <div class="section"> (or worse, .container itself). Global tag-balance hooks will NOT catch this when the file remains globally balanced. The cascade: from the orphan close onward, every subsequent <div class="section"> renders at a different DOM depth — sections after the break escape .container and render full-bleed at viewport width (e.g. 1905px instead of 992px), the cardinal symptom Maurice describes as "上下宽度又没对齐". Mitigations, in order of preference: (a) GENERATE with the resilient frame pattern from html-document-style SPEC §"Universal Layout Frame" — every section self-wraps .frame so a missing close on one section does NOT cascade to the next; (b) when forced to edit legacy .container > .section files, render in browser after insert and confirm document.querySelectorAll('.container > .section') returns the expected count AND all share the same getBoundingClientRect().left AND none are siblings of .container at body level; (c) the post-tool-html-visual-review.py hook now ships a check_section_isolation finding (severity ERROR) that detects this exact cascade — do not silence it. Lesson source: 2026-05-24 HARNESS_ENGINEERING_ARCHITECTURE-zh.html §4.6 insert on 2026-05-23 dropped sections #05-08 to body level for ~24h before visual report.

8. No HTML completion without fresh visual/runtime audit evidence. Opening the file is not enough. Before delivery, capture browser screenshots for desktop/tablet/mobile and run a browser-backed audit for horizontal scroll, component overflow, row/frame alignment, obvious empty grid holes, console errors, page errors, request failures, and HTTP 4xx/5xx responses. The same gate accepts file.html, file://, and live http(s) app URLs. Required baseline command: python3 skills/html-style-router/scripts/validate_html_visual_layout.py <file.html-or-url> --screenshots-dir <evidence-dir> --report-json <evidence-dir>/visual-layout-report.json. For Engineering Blueprint artifacts, also run: python3 skills/html-blueprint-style/scripts/validate_blueprint_layout.py <file.html> --screenshots-dir <evidence-dir>. If screenshots and geometry disagree, the screenshot wins and the defect must be fixed before claiming completion.

Typography Foundation (inherited base — read FIRST)

Before choosing a genre, every standalone HTML deliverable inherits the Typography Foundation (skills/typography-system) — the shared low-level typesetting layer (type scale, vertical rhythm, measure, grid, font stacks, CJK correctness) distilled from 10 canonical typography works. The genre/brand layer you pick below composes ON TOP of it and overrides only color, accent, and the brand font-family — never the scale, rhythm, measure, the responsive page frame, or the adaptive-color system.

Genre boundary (enforced 2026-06-25 after a visual swarm caught a real regression). A genre that re-declares the frame or the color system SEVERS the report from the foundation and breaks on a phone. Three failures are now mechanically gated by validate_typography.py (WARN; --strict blocks):

• genre-frame-hardcoded-gutter — a .html-frame must use calc(100% - var(--page-gutter-total)), NOT a constant calc(100% - 96px). A flat gutter over-squeezes the phone column and clips CJK glyphs at the edge.
• genre-stranded-dark — if the foundation's color-scheme: light dark is active, genre color tokens that feed body/html background MUST be light-dark() pairs (re-derived dark operands, not naive inversions). Flat light-only hex strands the foundation's dark mode as dead weight.
• stacked-table-no-label — the foundation owns the <560px labelled table reflow; a generator emitting a wide table MUST put data-label="<column header>" on every <td> so column identity survives the mobile stack.

1. Link/inline the foundation tokens FIRST: skills/typography-system/tokens/typography.css (Latin-first mixed font stack, :lang(zh) auto body-leading 1.75, bounded measure, font-synthesis:none, CJK text-autospace + line-break:strict + word-break:keep-all, 8pt spacing ramp, modular scale, neutral ink/paper). Its .html-frame composes with the --page-max layout frame in §"Cross-Style CJK/Layout Mandatory Rules" below.
2. Apply the genre style skill from the Routing Table for color + accent + brand font.
3. Validate before delivery: python3 skills/typography-system/scripts/validate_typography.py <file.html>
4. Capture visual/runtime evidence before delivery: python3 skills/html-style-router/scripts/validate_html_visual_layout.py <file.html-or-url> --screenshots-dir <evidence-dir> --report-json <evidence-dir>/visual-layout-report.json. Then run the genre-specific visual audit when available and manually inspect the generated desktop/tablet/mobile screenshots plus JSON runtime report for alignment, overflow, clipping, blank grid holes, console/page errors, and broken network resources.

Full detail: typography-system/SKILL.md + LAWS.md. The CJK mandatory rules below are the human-readable restatement of the foundation's CJK laws; the foundation CSS implements them.

Routing Table

Document Type	Signal Keywords	Style Skill	Design System
Documentation	guide, manual, handbook, how-to, tutorial, documentation, reference, spec, specification, onboarding	html-document-style	Claude Warm Academic Humanism
Proposal / Kickoff	proposal, kickoff, pitch, plan, initiative, charter, business case	html-document-style	Claude Warm Academic Humanism
Whitepaper / Thought Leadership	whitepaper, white paper, thought leadership, perspective, vision, position paper, manifesto	html-document-style	Claude Warm Academic Humanism
Internal Communication	memo, announcement, newsletter, update, changelog, release notes, postmortem	html-document-style	Claude Warm Academic Humanism
Research Report	research, report, analysis, findings, study, survey, investigation, assessment, evaluation	html-economist-style	The Economist Editorial
Market / Competitive	market analysis, competitive landscape, benchmark, comparison, due diligence, competitive intel	html-economist-style	The Economist Editorial
Briefing / Editorial	briefing, executive summary, brief, digest, intelligence, situation report, sitrep	html-economist-style	The Economist Editorial
Policy / Regulatory	policy analysis, regulatory, compliance review, legal analysis, risk assessment, audit	html-economist-style	The Economist Editorial
Strategy / Consulting	strategy, roadmap, transformation, operating model, capability, recommendation, board report, consulting	html-mckinsey-style	McKinsey Blue
Executive Decision	CEO briefing, board deck, decision memo, strategic options, investment case, go/no-go	html-mckinsey-style	McKinsey Blue
Financial Report	financial report, earnings, valuation, portfolio, revenue, P&L, balance sheet, cashflow	html-bloomberg-style	Bloomberg Terminal
Data Dashboard	dashboard, KPI report, metrics, data analysis, performance data, market data, risk dashboard	html-bloomberg-style	Bloomberg Terminal
Investment / Trading	investment memo, trading, fund, allocation, exposure, returns, yield, benchmark data	html-bloomberg-style	Bloomberg Terminal
AI Agent Biography / CLI Story	agent introduction, agent profile, CLI tool story, fork-vs-upstream, dev-blog history, project mythology, character-driven postmortem	html-hermes-style	Hermes Terminal (retro TUI / mythological)
Knowledge Poster / Social Card	知识卡片, 海报, 公众号配图, 推文封面, knowledge poster, social card, 一图读懂, 双语海报	html-knowledge-poster-style	Bilingual Knowledge Poster (themeable yellow/blue)
Archival Brutalist Note	档案, 复盘, dossier, archive note, condition map, positioning, 紧凑信息密度, Swiss brutalist, takeaway grid	html-archive-brutalist-style	Swiss Archival Brutalist (cream + serif + mono)
Neon-Pixel Dark Cover	封面, dark cover, edition, 榜单, Top-N list, a16z-style, neon, tech-editorial dark, Geist Pixel, pixel display, pixel typography, 像素字体, 像素封面	html-neon-pixel-style	Neon-Pixel Dark (black + neon magenta/green)
Engineering Blueprint	技术图解, 拆解, 原理, blueprint, schematic, spec sheet, 参数对比, 工程海报, MOD panels	html-blueprint-style	Engineering Blueprint (graph-paper + mono + gauges)
Academic Figure	论文配图, 实证结果, figure, benchmark plot, ablation, multi-panel chart, 学术图表, NeurIPS/arXiv	html-paper-figure-style	Academic Figure (white + muted categorical + captions)

Genre family note (2026-06-26). The five rows above are the visual/poster family — single-surface artifacts (a card, a cover, a figure page), pixel-sampled from real references into skills/html-<genre>-style/SPEC.md + a reference template under examples/genre/. They differ from the document/report genres above (multi-section deliverables). Pick by ARTIFACT SHAPE first: a shareable single card/cover/figure → visual family; a multi-section report → document family.

Geist Pixel route note (2026-07-06). Geist Pixel, pixel display, pixel typography, or 像素字体 are typography signals, not a standalone genre. Route to typography-system + html-neon-pixel-style only when the requested artifact is a single-surface dark/neon cover, countdown, product moment, or short Latin wordmark. For reports, decks, body copy, product UI, or CJK prose, keep the document genre and do not use the pixel display face.

Decision Logic

IF document purpose is:
  - to EXPLAIN, GUIDE, PROPOSE, or INSPIRE
  → use html-document-style (Claude humanistic)

  - to ANALYZE, ARGUE, COMPARE, or BRIEF (editorial)
  → use html-economist-style (Economist editorial)

  - to RECOMMEND, STRATEGIZE, or DRIVE DECISIONS (consulting)
  → use html-mckinsey-style (McKinsey Blue)

  - to PRESENT DATA, QUANTIFY, or MONITOR METRICS (financial)
  → use html-bloomberg-style (Bloomberg Terminal)

  - to PROFILE AN AI AGENT or CLI TOOL with character/personality (biography)
  → use html-hermes-style (Hermes Terminal)

  - to deliver ONE idea as a shareable VISUAL (card / cover / figure / blueprint)
  → visual family: knowledge-poster (social card) · archive-brutalist (dense Swiss note)
    · neon-pixel (dark cover) · blueprint (technical schematic) · paper-figure (academic charts)

Disambiguation Rules

1. Title contains "报告/report/analysis/briefing/assessment" → Economist
2. Title contains "指南/guide/手册/manual/方案/proposal" → Claude
3. Title contains "战略/strategy/roadmap/transformation/recommendation" → McKinsey
4. Title contains "财务/financial/dashboard/KPI/metrics/投资" → Bloomberg
5. Content is primarily data-driven with tables and comparisons → Economist or Bloomberg (Bloomberg if >50% numerical)
6. Content is primarily narrative with step-by-step instructions → Claude
7. Content structured as "conclusion first, then evidence" → McKinsey
8. Audience is board / C-suite with action required → McKinsey
9. Audience is analysts / traders / finance teams → Bloomberg
10. Audience is practitioners / developers / operators → Claude
11. Subject IS an AI agent or CLI tool with personality/identity → Hermes
12. Artifact is ONE shareable card/卡片/海报/公众号配图 → knowledge-poster (themeable)
13. Cream + huge SERIF transform headline + mono labels + dense grid → archive-brutalist
14. Dark/black cover + neon + bold condensed + 榜单/edition → neon-pixel
15. Geist Pixel / pixel display / pixel typography / 像素字体 + single-surface cover/countdown/product moment → neon-pixel + --font-stack-pixel-display; if the target is body/report/UI/CJK prose, keep the non-pixel document genre
16. Graph-paper + MOD panels + gauges/schematics + 技术拆解 → blueprint
17. White multi-panel (a)-(e) charts + Fig. captions + 论文配图 → paper-figure
18. When ambiguous → default to Claude humanistic (safer, most versatile)

Style Summary Comparison

Dimension	Claude Humanistic	Economist Editorial	McKinsey Blue	Bloomberg Terminal
Feeling	Warm, academic	Authoritative, editorial	Corporate, decisive	Data-dense, technical
Page bg	Cream #F3F0E9	White #FFFFFF	White + gray sections	Dark #0A0E17
Accent	Terracotta #D67052	Red #E3120B	Deep Blue #003A70	Amber #FF9F1C
Headlines	Serif (Crimson Pro)	Sans (DM Sans)	Sans heavy (Inter 900)	Sans (Inter)
Body text	Sans (Source Sans 3)	Serif (Source Serif 4)	Sans (Inter)	Sans + Mono
Data font	--	--	Sans	Monospace (JetBrains)
Corners	10px	0px	0px	4px
Shadows	Paper (3 tiers)	None	None	Glow borders
Density	Spacious	Dense	Structured	Maximum
Container	1100px	960px	1040px	1200px / full
Content model	Narrative	Editorial argument	Pyramid principle	Data-first
Best for	Guides, proposals	Reports, briefings	Strategy, board decks	Financial, dashboards

Usage

When this skill is triggered:

1. Read the document title, purpose, and audience
2. Match against the routing table above
3. Announce the routing decision: "Style: [Claude Humanistic / Economist Editorial]"
4. Load the corresponding skill: html-document-style or html-economist-style
5. Follow that skill's full specification for the HTML output

Examples

• "Gemma 在中国 To-B 场景中的价值" → contains "调研报告", analysis, comparison → Economist
• "Project Kickoff -- Tax Compliance Platform" → kickoff, proposal → Claude
• "React Performance Best Practices Guide" → guide, how-to → Claude
• "Q3 2026 AI Model Competitive Landscape" → competitive, landscape, analysis → Economist
• "API Integration Handbook v2.0" → handbook, documentation → Claude
• "China GenAI Regulatory Compliance Briefing" → briefing, regulatory, policy → Economist
• "AI智能体事故定级机制" → strategy, recommendation, mechanism, 机制 → McKinsey

Composable axes (full version only)

The full AI-Fleet build of this router adds four composable axes that are not bundled in this public pack because they depend on private infra (a brand-token cache, movement recipe cards, a PlantUML→SVG pipeline):

• Brand Identity Sidecar — overlay a brand's tokens ("make it look like Stripe / Linear / Notion") onto the chosen genre.
• Cover/Hero Treatment Sidecar — swappable hero treatments via 4 CSS knobs.
• Aesthetic-Movement Lane — 10 art-movement vibes (synthwave / bauhaus / art-deco / memphis / risograph …) as a fan-out vocabulary.
• Software-Modeling Diagram Lane — PlantUML → inline SVG.

Genre × axis compose cleanly: genre owns layout, the axis overrides only color / accent / brand-font — never the typography foundation's scale, rhythm, measure, or CJK rules.

Cross-Style CJK/Layout Mandatory Rules

These rules apply to ALL 4 design systems. They are non-negotiable for Chinese-language HTML documents. They are the human-readable restatement of the Typography Foundation CJK laws (skills/typography-system/LAWS.md); linking typography-system/tokens/typography.css implements most of them automatically (Latin-first stack, :lang(zh) leading, font-synthesis:none, line-break:strict, word-break:keep-all, text-autospace).

1. Zero Scrollbar Policy

html, body { overflow-x: hidden } is mandatory. Additionally, every container that might hold dynamic content (.table-wrapper, .flow-container, .card-grid, .code-block) must use overflow-x: hidden, NEVER auto. Horizontal scrollbars are unacceptable in executive-facing documents. Use table-layout: fixed + word-break: break-word on all tables.

2. Mixed CJK/Latin Proper Name Protection

English proper names in Chinese text (e.g., "Air Canada", "Amazon Kiro", "Replit AI") will break at word boundaries in narrow containers. word-break: keep-all does NOT prevent this — it only affects CJK characters. Fix: use   between words of multi-word proper names that must stay together. Scan ALL card bodies, list items, and narrow-container text for this issue.

3. Hero/Cover Content Width Alignment

The hero/cover background may be full-width, but the hero CONTENT must align pixel-perfectly with the body sections below. Use one shared frame token for header content, body content, tables, and cards:

:root { --page-max: 1040px; --page-gutter: clamp(16px, 3vw, 48px); --page-gutter-total: clamp(32px, 6vw, 96px); }
.html-frame, .doc-frame, .report-frame {
  width: min(var(--page-max), calc(100% - var(--page-gutter-total)));
  margin-inline: auto;
}
.cover, .hero-full, .report-cover { padding-inline: 0; }
.cover > .html-frame,
.hero-full > .html-frame,
.report-cover > .html-frame,
main.html-frame,
main.report-frame { margin-inline: auto; }

Never use horizontal padding on the hero container to constrain content, such as padding-inline: 8vw, while the body uses a separately centered max-width. That creates different reference frames and causes the wide-screen mismatch where the header starts far left of the body column. Before delivery, inspect desktop and mobile widths: hero title, hero metadata, first section heading, and data tables should share the same left edge unless a deliberate asymmetric layout is documented.

4. Flow Diagram Node Limits

Never put >4 flow nodes in a single flex row. For 5-6 node pipelines, split into 2 rows (3+3 or 3+2) with a vertical connector. Always use flex-wrap: nowrap per row to prevent unpredictable wrapping. Set flex-shrink: 1 on nodes to allow compression.

5. Table Header No-Wrap Ban

Never use white-space: nowrap on thead th in Chinese documents. Chinese headers + content easily exceed container width. Use white-space: normal + table-layout: fixed universally.

6. Pseudo-Element Overlay Simplicity

Do not add decorative ::before / ::after gradient overlays on dark hero backgrounds unless absolutely necessary. Even subtle overlays create visible color seams. If the base gradient is well-designed, content: none the overlay.

7. Table Label Column No-Break Rule

Table label columns (first column with row headers like "模型池", "企业版", "Claude Code 文档") must NEVER break CJK compound terms mid-phrase. Set th:first-child, td:first-child { white-space: nowrap; min-width: 120px; }. Data columns with long content may wrap with word-break: break-word. Rule: label columns never wrap; data columns may wrap.

8. Multi-Column Comparison Table Width Control

When a table has 4+ data columns (e.g., 1 label column + 4 provider columns), the total content width easily exceeds the container. Fix: use table-layout: fixed with explicit percentage widths — label column ~12%, each data column equal share of remaining space. Add word-break: break-word on data cells. Never rely on white-space: nowrap for ALL cells in wide tables — it guarantees overflow. Pattern: table.compare-table { table-layout: fixed; width: 100%; } + first-child 12% + others equal. This prevents the last column from being clipped.