rich-page

What this skill does

# rich-page

Build an opinionated, visually distinctive **single self-contained HTML page** from an arbitrary source — explainer, research write-up, PRD, pitch, one-pager, distilled report, "make this less boring" rebuild. The output is one `.html` file that renders identically when DM'd to anyone: CDN-loaded libraries are allowed (they're stable), but every image is base64-inlined so there are no external file references.

The point of this skill, in the spirit of Google Research's [Generative UI](https://generativeui.github.io/) work: **generate the interface, not just the content.** Most "explainers" written by AI default to prose with a card grid. Reach further. A bar chart with the SLO line called out. A Mermaid sequence of the actual protocol. A scroll-tied walkthrough of how a request travels through the system. A click-to-detail architecture diagram. Typography that signals intent. The visual treatment is the contribution.

This skill is a **four-phase workflow**. The split between Phase 2 (visual plan) and Phase 3 (build) is what keeps the page focused — without it, every section becomes a card grid and the page reverts to AI slop.

## When this skill applies

Trigger for explicit asks ("make me a rich page about X", "turn this PDF into something visual", "build me a deck"), but also for implicit ones:

- "I want something I can show the team about Y"
- "explain Z in a visual way" / "more visual than a doc"
- "make this less boring" / "give it some eye candy"
- "distill our research into a page"
- "I want a one-pager / pitch / PRD page for [thing]"
- "rebuild that page" / "redo it with more visuals"
- "turn this into something I can present"

If the user wants a **plain Markdown doc**, hand off to `technical-writer`. If they want a **review of code or a PR**, use `reviewer`. If they want **maintainable component code a team will edit over time** (React/Vue/Svelte components shipping to production), use `frontend-design` — rich-page produces one-shot HTML artifacts (DM-able files, internal pages, archival reports), not living software. If they show up with a source (PDF, markdown, notes, URL) and ask for a "rich", "visual", "interactive", "less-boring" treatment, this skill fits.

## Workflow at a glance

1. **Intake.** Read the source if there is one. Otherwise collect topic, audience, language, output path. Identify candidate "visual moments" — places where prose would lose the lesson.
2. **Visual plan.** Pick the visual direction (font pair, palette, vibe), draft the section list, and choose 4–7 centerpiece visuals from the catalog with the *technique* named for each. Stop and confirm (unless the user said "just go").
3. **Build the HTML.** Write one self-contained `.html` file: theme CSS, CDN library tags, base64-inlined images, inline SVG diagrams, inline JS for interactivity. No external image references.
4. **Self-check + handoff.** Parse the HTML, confirm self-containment, report the path.

Each phase below says what to do, what supporting file to load, and what output the user should see.

---

## Phase 1 — Intake

Goal: understand the source well enough to plan the page. Don't over-interview.

### If a source file is provided

Read it end-to-end with the `Read` tool. For long PDFs (>10 pages), use the `pages` parameter to chunk it — don't skip to the conclusion. You want the table of contents, the figures, the methodology, the limitations, the conclusion. Note:

- **Title, author, attribution, date** — for the hero block and footer.
- **The source's own visual language** — accent colors, fonts. The default palette is dark + coral; override if the source uses a distinctive color (e.g. orange thesis cover, a brand identity).
- **The source's language** — Dutch source → Dutch page. French source → French page. Keep technical terms in their original language as the source does.
- **Candidate visual moments.** Scan for any of (with the matching pattern from `references/interaction-patterns.md`):
  - **Quantitative claims, distributions, time series** → annotated chart (Chart.js)
  - **Same metric across categories** → small multiples (Observable Plot)
  - **"With X vs without X" / "naïve vs"** → comparison toggle
  - **Architecture with 3–6 components** → hover/click node diagram (inline SVG)
  - **Protocol / handshake / API dance** → sequence diagram (Mermaid or custom)
  - **Cyclic processes (loop, retry, observe-act)** → animated process loop
  - **Parameters with non-obvious effects** → slider + live chart
  - **Phases / milestones / staged work** → click-to-expand timeline
  - **"We reduced N to M"** → aggregation animation
  - **A genuinely sequential walkthrough** → scroll-tied sequence (GSAP)
  - **A section with 4+ sub-views** → tabbed view
- **Hard numbers** for the key-facts strip (page count, sections, sample size, metrics).
- **Placeholders the source contains** (`[TBD]`, `[forthcoming]`). Mirror them; don't invent data.

### If no source file, only a topic

Bundle one `AskUserQuestion` call covering:

- **Topic** — what's the page about? One sentence.
- **Audience** — who reads this?
- **Language** — default to whatever the user is writing in.
- **Output path** — default to `./<topic-slug>.html` in CWD.
- **Source material** — any docs, links, or notes? (Optional)

Don't ask four separate questions. Bundle into one.

### Escape hatch — "just go" phrases

If the user's first message contains any of these phrases, **skip the Phase 2 pause** and move directly through Phase 2 + Phase 3 in the same reply:

`"just go"` · `"just build it"` · `"build it"` · `"don't ask"` · `"skip the plan"` · `"go ahead"` · `"do it"`

Use sensible defaults for anything you'd otherwise have asked about. Still emit a **3–5 line prose summary** of your decisions (direction + sections + visuals, in flat prose, no tables, no section list, no inventory block) at the top of the reply so the user can see what you decided before scrolling to the artifact — they just don't have to approve it. The structured Phase 2 outputs (visual direction paragraph, section list, visual inventory table) belong to the gated path; in escape-hatch mode you produce the artifact directly and the summary substitutes for them. Phase 2 below references this same canonical list.

---

## Phase 2 — Visual plan

Produce three things in one reply: **visual direction**, **section list**, **visual inventory**.

### 2a. Visual direction (one short paragraph)

Name the font pair, the OKLCH palette (3 colors), the overall vibe, the target page shape. Something like:

> **Direction.** Bold editorial — Archivo Black display paired with Space Grotesk body. Palette: deep slate `oklch(0.18 0.02 260)` background, off-white `oklch(0.94 0.01 260)` text, saturated coral `oklch(0.70 0.18 40)` accent. Cyan `oklch(0.82 0.14 195)` as the "other side" in comparisons. Long scrolling page (~7 sections), sticky nav, animated conic-gradient hero, sparse motion (fade-up on reveal only).

Load `references/design-system.md`. It has the font pair catalogue, OKLCH primer, layout primitives, hero recipe, and the AI-slop avoid list. Pick a direction that fits the source's tone — don't default to "modern corporate" for every page.

### 2b. Section list

A scroll-page rhythm that works for most topics:

```
1.  Hero           — title, attribution, scroll cue, link to source
2.  Sticky nav     — anchors to every below section
3.  Key facts      — 5–8 numbers, large type, single row
4.  The problem    — why this exists, plain prose
5–9. Content       — 4–6 thematic sections, each a chunk of the source
10. Limitations    — what doesn't work / open questions (if source has any)
11. Conclusion     — short, the source's takeaway in plain language
12. Footer         — author, attribution, link back to source
```

For **short pages (≤ 5 sections)**, drop the sticky nav — it's overhead the reader doesn't need when the whole page fits in 2–3 viewports. Same for the limitations section if the source doesn't have any.

Vary