HTML Fancy Report
Turn information into beautiful, self-contained single-file HTML documents. This skill captures the philosophy, design system, and practical patterns for creating reports that people actually read — not skim.
Philosophy
HTML is often the best medium for communication
Many documents we produce — reports, plans, overviews, summaries — are fundamentally spatial, visual, or interactive. Flattening them into linear text makes them harder to consume. A well-designed HTML page communicates structure at a glance: the reader sees hierarchy, relationships, and emphasis before reading a single word.
When HTML beats plain text or slides:
| Situation |
Why HTML |
| Architecture/system overviews |
Boxes and arrows show structure better than paragraphs |
| Product landing pages |
Visual hierarchy guides the reader through features |
| Project status reports |
Small charts, colored timelines, visual priority |
| Comparison documents |
Side-by-side layouts let readers compare directly |
| Code review summaries |
Annotated diffs, severity tags, jump links |
| Design documents |
Color swatches, type scales, component sheets |
| Incident post-mortems |
Timeline visualization, log excerpts, checklist |
The self-contained principle
Every report should be a single .html file with inline CSS and JS. No framework, no build step, no external dependencies (except images when necessary). Open it in a browser — it works. This means:
- Zero friction to view — no
npm install, no build, no server
- Permanent and portable — the file will render the same way in 10 years
- Easy to share — email it, commit it, drag it into a browser
- The medium matches the message — the file itself embodies the philosophy
Interaction beats description
Motion and interaction cannot be described in words — they must be felt. A small interactive element (a hover effect, a collapsible section, a tab switcher) communicates in half a second what a paragraph never could. Don't overdo it, but one well-placed interaction per page makes it feel alive.
Design System
Color Palettes
Don't default to generic blue. Pick colors that match the topic. One color should dominate (60-70% visual weight), with 1-2 supporting tones and one sharp accent.
| Palette |
Background |
Surface |
Accent |
Best for |
| Editorial Warm |
#FBFAF8 ivory |
#FFFFFF white |
#C75B39 clay |
Reports, docs, long-form |
| Dark Tech |
#0a0a0b deep |
#111114 card |
cyan/teal |
Dashboards, dev tools |
| Forest Fresh |
#FAFBF9 |
#FFFFFF |
#2C5F2D |
Nature, health, sustainability |
| Midnight Navy |
#F8F9FB |
#FFFFFF |
#1E2761 |
Enterprise, finance, legal |
| Warm Stone |
#FAFAF9 stone |
#FFFFFF |
#B85042 terracotta |
Creative, design, lifestyle |
| Charcoal Minimal |
#FAFAFA |
#FFFFFF |
#36454F |
Architecture, minimal products |
Dark backgrounds: Use them sparingly — best for hero sections, architecture diagrams, or a "sandwich" structure (dark → light → dark).
Typography
Use system fonts to avoid external dependencies:
--serif: ui-serif, Georgia, "Times New Roman", Times, serif;
--sans: system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
--mono: ui-monospace, "SF Mono", Menlo, Monaco, Consolas, monospace;
Pairing rule: Serif headings + sans-serif body = editorial, trustworthy. Sans-serif headings + sans-serif body = modern, clean.
| Element |
Size |
Weight |
| Page title |
clamp(42px, 6vw, 68px) |
500 (serif) |
| Section header |
26-30px |
500 |
| Card title |
16-20px |
500-600 |
| Body text |
14-16px |
400 |
| Captions/labels |
10-12px |
400 |
Spacing
- 0.5" (48px) minimum edge margins
- 0.3-0.5" (12-20px) between content blocks
- Section padding: 80-120px vertical
- Leave breathing room — don't fill every pixel
Layout Patterns
Every section should have a visual element. Text-only sections are forgettable.
- Hero with visual — Title + subtitle on the left, an SVG diagram or illustration on the right (2-column grid)
- Card grid —
grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)) — 3-6 cards with icons
- Two-column install — Side-by-side options (e.g., macOS vs Windows install)
- Numbered list — For trust/safety, steps, or principles — number + heading + description
- Dark card in light section — One dark-background card floating in a light section for emphasis
- Horizontal scroll gallery — Screenshots or images in a horizontal strip
- Pill row — Tech tags, categories, labels as rounded pills
- CTA box — Centered, bordered card with a call to action and big buttons
Avoid (Hallmarks of AI-Generated Slides/Pages)
- Centered body text — left-align paragraphs, center only short titles
- Accent lines under titles — use whitespace or background instead
- Default blue color scheme — pick colors specific to the topic
- Text-only layouts — add at least one visual element per section
- Mixing random spacing — choose consistent gaps and stick to them
- Low-contrast text — ensure readability against backgrounds
Practical Patterns
Base HTML Template
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Document Title</title>
<style>
:root {
/* Define your palette here */
}
* { box-sizing: border-box; margin: 0; padding: 0; }
html { scroll-behavior: smooth; }
body {
background: var(--bg);
color: var(--text);
font-family: var(--sans);
line-height: 1.6;
-webkit-font-smoothing: antialiased;
}
</style>
</head>
<body>
<!-- Content -->
</body>
</html>
SVG Diagrams Inline
Inline SVG is one of HTML's superpowers. Use it for architecture diagrams, flowcharts, and data visualizations. The agent can draw precise diagrams that convey structure instantly.
Key SVG patterns:
- Rounded rects (
rx="8") for boxes/nodes
- Dashed lines (
stroke-dasharray="5 3") for relationships
- Color coding — warm for primary, cool for secondary, neutral for supporting
- Small labels (font-size 9-11px) for annotations
- A caption div below the SVG for context
Interactive Elements Worth Adding
- Copy buttons on code blocks — small, satisfying, useful
- Smooth scroll —
html { scroll-behavior: smooth; } and anchor links
- Card hover effects — subtle lift (
translateY(-3px)) + shadow
- Collapsible sections —
<details>/<summary> for FAQs or deep dives
- Tab switchers — for comparing options or showing multiple languages
Responsive Design
Always include at least two breakpoints:
- Tablet (768px) — switch to single column, reduce padding
- Phone (480px) — smaller fonts, full-width cards
Test by resizing the browser. Scroll-snap can cause issues on mobile — disable it in media queries.
Typography & Statistics
For data-heavy reports, use large stat callouts:
- Big numbers (60-72pt) with small labels below
- One key metric per "stat card"
- Visual hierarchy: number > label > context
Workflow
Before Writing Code
- Identify the audience — developer? executive? general public?
- Choose a palette — pick from the table above, adapted to the topic
- Sketch the sections — what are the 4-7 sections the reader needs?
- Pick a visual for each section — diagram, cards, gallery, pills, CTA
While Writing
- Start with the hero — title, subtitle, one visual element
- Write one section at a time, top to bottom
- Add interaction last — it's seasoning, not the meal
- Keep the CSS organized with clear section comments (
/* ── Section Name ── */)
After Writing
- Open in a browser and scroll through
- Resize to mobile width and verify readability
- Check contrast — can you read everything comfortably?
- Remove anything that doesn't earn its place
Questions to ask before starting
If the user's request is vague, clarify:
- What's the primary message? (one sentence)
- Who will read this? (audience)
- How many sections? (scope — aim for 4-7)
- Any existing brand colors or assets to incorporate?
Bundled Reference: HTML Effectiveness Demos
The references/html-effectiveness/ directory contains 20 concrete demos from ThariqS/html-effectiveness. Each demo is a self-contained .html file. Each is a self-contained .html file — open directly in a browser.
Read references/html-effectiveness/index.html first — it's the catalog page and the single best example of the design system in practice (warm editorial palette, card grid, SVG thumbnails, responsive layout).
When to consult specific demos
| User asks for |
Look at these demos |
| A product landing page or project overview |
index.html (the catalog structure), 09-slide-deck.html (section-based layout) |
| A comparison or code review summary |
03-code-review-pr.html, 17-pr-writeup.html, 01-exploration-code-approaches.html |
| A design system or style guide |
05-design-system.html, 06-component-variants.html |
| A status report or incident post-mortem |
11-status-report.html (weekly status with charts), 12-incident-report.html (timeline + log excerpts) |
| An architecture diagram or flowchart |
04-code-understanding.html (module map), 13-flowchart-diagram.html (clickable flow) |
| A slide deck for presentations |
09-slide-deck.html (arrow-key navigation) |
| An interactive tool or editor |
18-editor-triage-board.html (drag + export), 20-editor-prompt-tuner.html (live preview) |
| Visual design exploration |
02-exploration-visual-designs.html (layout + palette options) |
| An explainer or tutorial |
14-research-feature-explainer.html (collapsible sections, tabbed code), 15-research-concept-explainer.html (interactive concept) |
How to use these references: Don't copy-paste. Study the design language — the spacing, the color use, the typography, how SVGs are used as thumbnails, how sections are structured. Then apply the same principles to the user's specific topic with a fresh design. The goal is to internalize the philosophy, not reproduce the examples.
1---2name: html-report3description: Create beautiful, self-contained single-file HTML reports, landing pages, and documents that are visual, interactive, and spatial. Use when the user wants to present information that would benefit from layout, color, diagrams, or interaction — such as project reports, product pages, architecture overviews, design documents, dashboards, slide decks, code review summaries, incident post-mortems, status reports, or any document where plain text would be too flat. Triggers include "create an HTML page", "make a report", "write a landing page", "build a dashboard", "present this information visually", or any request to communicate technical or business information in a polished, readable format.4---56# HTML Fancy Report78Turn information into beautiful, self-contained single-file HTML documents. This skill captures the philosophy, design system, and practical patterns for creating reports that people actually read — not skim.910## Philosophy1112### HTML is often the best medium for communication1314Many documents we produce — reports, plans, overviews, summaries — are fundamentally spatial, visual, or interactive. Flattening them into linear text makes them harder to consume. A well-designed HTML page communicates structure at a glance: the reader sees hierarchy, relationships, and emphasis before reading a single word.1516**When HTML beats plain text or slides:**1718| Situation | Why HTML |19|-----------|----------|20| Architecture/system overviews | Boxes and arrows show structure better than paragraphs |21| Product landing pages | Visual hierarchy guides the reader through features |22| Project status reports | Small charts, colored timelines, visual priority |23| Comparison documents | Side-by-side layouts let readers compare directly |24| Code review summaries | Annotated diffs, severity tags, jump links |25| Design documents | Color swatches, type scales, component sheets |26| Incident post-mortems | Timeline visualization, log excerpts, checklist |2728### The self-contained principle2930Every report should be a **single `.html` file** with inline CSS and JS. No framework, no build step, no external dependencies (except images when necessary). Open it in a browser — it works. This means:3132- **Zero friction** to view — no `npm install`, no build, no server33- **Permanent and portable** — the file will render the same way in 10 years34- **Easy to share** — email it, commit it, drag it into a browser35- **The medium matches the message** — the file itself embodies the philosophy3637### Interaction beats description3839Motion and interaction cannot be described in words — they must be felt. A small interactive element (a hover effect, a collapsible section, a tab switcher) communicates in half a second what a paragraph never could. Don't overdo it, but one well-placed interaction per page makes it feel alive.4041## Design System4243### Color Palettes4445Don't default to generic blue. Pick colors that match the topic. One color should dominate (60-70% visual weight), with 1-2 supporting tones and one sharp accent.4647| Palette | Background | Surface | Accent | Best for |48|---------|-----------|---------|--------|----------|49| **Editorial Warm** | `#FBFAF8` ivory | `#FFFFFF` white | `#C75B39` clay | Reports, docs, long-form |50| **Dark Tech** | `#0a0a0b` deep | `#111114` card | cyan/teal | Dashboards, dev tools |51| **Forest Fresh** | `#FAFBF9` | `#FFFFFF` | `#2C5F2D` | Nature, health, sustainability |52| **Midnight Navy** | `#F8F9FB` | `#FFFFFF` | `#1E2761` | Enterprise, finance, legal |53| **Warm Stone** | `#FAFAF9` stone | `#FFFFFF` | `#B85042` terracotta | Creative, design, lifestyle |54| **Charcoal Minimal** | `#FAFAFA` | `#FFFFFF` | `#36454F` | Architecture, minimal products |5556**Dark backgrounds**: Use them sparingly — best for hero sections, architecture diagrams, or a "sandwich" structure (dark → light → dark).5758### Typography5960Use system fonts to avoid external dependencies:6162```css63--serif: ui-serif, Georgia, "Times New Roman", Times, serif;64--sans: system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;65--mono: ui-monospace, "SF Mono", Menlo, Monaco, Consolas, monospace;66```6768**Pairing rule**: Serif headings + sans-serif body = editorial, trustworthy. Sans-serif headings + sans-serif body = modern, clean.6970| Element | Size | Weight |71|---------|------|--------|72| Page title | `clamp(42px, 6vw, 68px)` | 500 (serif) |73| Section header | 26-30px | 500 |74| Card title | 16-20px | 500-600 |75| Body text | 14-16px | 400 |76| Captions/labels | 10-12px | 400 |7778### Spacing7980- 0.5" (48px) minimum edge margins81- 0.3-0.5" (12-20px) between content blocks82- Section padding: 80-120px vertical83- Leave breathing room — don't fill every pixel8485### Layout Patterns8687Every section should have a visual element. Text-only sections are forgettable.88891. **Hero with visual** — Title + subtitle on the left, an SVG diagram or illustration on the right (2-column grid)902. **Card grid** — `grid-template-columns: repeat(auto-fill, minmax(300px, 1fr))` — 3-6 cards with icons913. **Two-column install** — Side-by-side options (e.g., macOS vs Windows install)924. **Numbered list** — For trust/safety, steps, or principles — number + heading + description935. **Dark card in light section** — One dark-background card floating in a light section for emphasis946. **Horizontal scroll gallery** — Screenshots or images in a horizontal strip957. **Pill row** — Tech tags, categories, labels as rounded pills968. **CTA box** — Centered, bordered card with a call to action and big buttons9798### Avoid (Hallmarks of AI-Generated Slides/Pages)99100- Centered body text — left-align paragraphs, center only short titles101- Accent lines under titles — use whitespace or background instead102- Default blue color scheme — pick colors specific to the topic103- Text-only layouts — add at least one visual element per section104- Mixing random spacing — choose consistent gaps and stick to them105- Low-contrast text — ensure readability against backgrounds106107## Practical Patterns108109### Base HTML Template110111```html112<!doctype html>113<html lang="en">114<head>115<meta charset="utf-8">116<meta name="viewport" content="width=device-width, initial-scale=1">117<title>Document Title</title>118<style>119 :root {120 /* Define your palette here */121 }122 * { box-sizing: border-box; margin: 0; padding: 0; }123 html { scroll-behavior: smooth; }124 body {125 background: var(--bg);126 color: var(--text);127 font-family: var(--sans);128 line-height: 1.6;129 -webkit-font-smoothing: antialiased;130 }131</style>132</head>133<body>134 <!-- Content -->135</body>136</html>137```138139### SVG Diagrams Inline140141Inline SVG is one of HTML's superpowers. Use it for architecture diagrams, flowcharts, and data visualizations. The agent can draw precise diagrams that convey structure instantly.142143Key SVG patterns:144- Rounded rects (`rx="8"`) for boxes/nodes145- Dashed lines (`stroke-dasharray="5 3"`) for relationships146- Color coding — warm for primary, cool for secondary, neutral for supporting147- Small labels (font-size 9-11px) for annotations148- A caption div below the SVG for context149150### Interactive Elements Worth Adding1511521. **Copy buttons** on code blocks — small, satisfying, useful1532. **Smooth scroll** — `html { scroll-behavior: smooth; }` and anchor links1543. **Card hover effects** — subtle lift (`translateY(-3px)`) + shadow1554. **Collapsible sections** — `<details>/<summary>` for FAQs or deep dives1565. **Tab switchers** — for comparing options or showing multiple languages157158### Responsive Design159160Always include at least two breakpoints:161- Tablet (768px) — switch to single column, reduce padding162- Phone (480px) — smaller fonts, full-width cards163164Test by resizing the browser. Scroll-snap can cause issues on mobile — disable it in media queries.165166### Typography & Statistics167168For data-heavy reports, use large stat callouts:169- Big numbers (60-72pt) with small labels below170- One key metric per "stat card"171- Visual hierarchy: number > label > context172173## Workflow174175### Before Writing Code1761771. **Identify the audience** — developer? executive? general public?1782. **Choose a palette** — pick from the table above, adapted to the topic1793. **Sketch the sections** — what are the 4-7 sections the reader needs?1804. **Pick a visual for each section** — diagram, cards, gallery, pills, CTA181182### While Writing1831841. Start with the hero — title, subtitle, one visual element1852. Write one section at a time, top to bottom1863. Add interaction last — it's seasoning, not the meal1874. Keep the CSS organized with clear section comments (`/* ── Section Name ── */`)188189### After Writing1901911. Open in a browser and scroll through1922. Resize to mobile width and verify readability1933. Check contrast — can you read everything comfortably?1944. Remove anything that doesn't earn its place195196## Questions to ask before starting197198If the user's request is vague, clarify:199- What's the primary message? (one sentence)200- Who will read this? (audience)201- How many sections? (scope — aim for 4-7)202- Any existing brand colors or assets to incorporate?203204## Bundled Reference: HTML Effectiveness Demos205206The `references/html-effectiveness/` directory contains 20 concrete demos from [ThariqS/html-effectiveness](https://github.com/ThariqS/html-effectiveness). Each demo is a self-contained `.html` file. Each is a self-contained `.html` file — open directly in a browser.207208**Read `references/html-effectiveness/index.html` first** — it's the catalog page and the single best example of the design system in practice (warm editorial palette, card grid, SVG thumbnails, responsive layout).209210### When to consult specific demos211212| User asks for | Look at these demos |213|---------------|---------------------|214| A product landing page or project overview | `index.html` (the catalog structure), `09-slide-deck.html` (section-based layout) |215| A comparison or code review summary | `03-code-review-pr.html`, `17-pr-writeup.html`, `01-exploration-code-approaches.html` |216| A design system or style guide | `05-design-system.html`, `06-component-variants.html` |217| A status report or incident post-mortem | `11-status-report.html` (weekly status with charts), `12-incident-report.html` (timeline + log excerpts) |218| An architecture diagram or flowchart | `04-code-understanding.html` (module map), `13-flowchart-diagram.html` (clickable flow) |219| A slide deck for presentations | `09-slide-deck.html` (arrow-key navigation) |220| An interactive tool or editor | `18-editor-triage-board.html` (drag + export), `20-editor-prompt-tuner.html` (live preview) |221| Visual design exploration | `02-exploration-visual-designs.html` (layout + palette options) |222| An explainer or tutorial | `14-research-feature-explainer.html` (collapsible sections, tabbed code), `15-research-concept-explainer.html` (interactive concept) |223224**How to use these references**: Don't copy-paste. Study the design language — the spacing, the color use, the typography, how SVGs are used as thumbnails, how sections are structured. Then apply the same principles to the user's specific topic with a fresh design. The goal is to internalize the philosophy, not reproduce the examples.
luochang212