R
Ranger
Created Mar 2, 2026
Low Risk with warnings
2 findings
INFO
Skill manifest does not include a 'license' field. Specifying a license helps users understand usage terms.
Remediation Add 'license' field to SKILL.md frontmatter (e.g., MIT, Apache-2.0)
MEDIUM
Detects protocol manipulation via capability inflation in skill discovery: perfect
Remediation Review and remove skill discovery abuse pattern
Scanned in 0.031s
Description
Generate beautiful, self-contained HTML pages that visually explain systems, code changes, plans, and data. Use when the user asks for a diagram, architecture overview, diff review, plan review, project recap, comparison table, or any visual explanation of technical concepts. Also use proactively when you are about to render a complex ASCII table (4+ rows or 3+ columns) — present it as a styled HTML page instead.
Details
License
MIT
Compatibility
Requires a browser to view generated HTML files. Optional surf-cli for AI image generation.
Metadata
- author
- nicobailon
- version
- 0.5.0
Skill Files
Download .zip
SKILL.md
# Visual Explainer
Generate self-contained HTML files for technical diagrams, visualizations, and data tables. Always open the result in the browser. Never fall back to ASCII art when this skill is loaded.
**Proactive table rendering.** When you're about to present tabular data as an ASCII box-drawing table in the terminal (comparisons, audits, feature matrices, status reports, any structured rows/columns), generate an HTML page instead. The threshold: if the table has 4+ rows or 3+ columns, it belongs in the browser. Don't wait for the user to ask — render it as HTML automatically and tell them the file path. You can still include a brief text summary in the chat, but the table itself should be the HTML page.
## Workflow
### 1. Think (5 seconds, not 5 minutes)
Before writing HTML, commit to a direction. Don't default to "dark theme with blue accents" every time.
**Visual is always default.** Even essays, blog posts, and articles get visual treatment — extract structure into cards, diagrams, grids, tables.
Prose patterns (lead paragraphs, pull quotes, callout boxes) are **accent elements** within visual pages, not a separate mode. Use them to highlight key points or provide breathing room, but the page structure remains visual.
For prose accents, see "Prose Page Elements" in `./references/css-patterns.md`. For everything else, use the standard freeform approach with aesthetic directions below.
**Who is looking?** A developer understanding a system? A PM seeing the big picture? A team reviewing a proposal? This shapes information density and visual complexity.
**What type of content?** Architecture, flowchart, sequence, data flow, schema/ER, state machine, mind map, class diagram, C4 architecture, data table, timeline, dashboard, or prose-first page. Each has distinct layout needs and rendering approaches (see Diagram Types below).
**What aesthetic?** Pick one and commit. The constrained aesthetics (Blueprint, Editorial, Paper/ink) are safer — they have specific requirements that prevent generic output. The flexible ones (IDE-inspired) require more discipline.
**Constrained aesthetics (prefer these):**
- Blueprint (technical drawing feel, subtle grid background, deep slate/blue palette, monospace labels, precise borders) — see `websocket-implementation-plan.html` for reference
- Editorial (serif headlines like Instrument Serif or Crimson Pro, generous whitespace, muted earth tones or deep navy + gold)
- Paper/ink (warm cream `#faf7f5` background, terracotta/sage accents, informal feel)
- Monochrome terminal (green/amber on near-black, monospace everything, CRT glow optional)
**Flexible aesthetics (use with caution):**
- IDE-inspired (borrow a real, named color scheme: Dracula, Nord, Catppuccin Mocha/Latte, Solarized Dark/Light, Gruvbox, One Dark, Rosé Pine) — commit to the actual palette, don't approximate
- Data-dense (small type, tight spacing, maximum information, muted colors)
**Explicitly forbidden:**
- Neon dashboard (cyan + magenta + purple on dark) — always produces AI slop
- Gradient mesh (pink/purple/cyan blobs) — too generic
- Any combination of Inter font + violet/indigo accents + gradient text
Vary the choice each time. If the last diagram was dark and technical, make the next one light and editorial. The swap test: if you replaced your styling with a generic dark theme and nobody would notice the difference, you haven't designed anything.
### 2. Structure
**Read the reference material** before generating. Don't memorize it — read it each time to absorb the patterns.
- For text-heavy architecture overviews (card content matters more than topology): read `./templates/architecture.html`
- For flowcharts, sequence diagrams, ER, state machines, mind maps, class diagrams, C4: read `./templates/mermaid-flowchart.html`
- For data tables, comparisons, audits, feature matrices: read `./templates/data-table.html`
- For slide deck presentations (when `--slides` flag is present or `/generate-slides` is invoked): read `./templates/slide-deck.html` and `./references/slide-patterns.md`
- For prose-heavy publishable pages (READMEs, articles, blog posts, essays): read the "Prose Page Elements" section in `./references/css-patterns.md` and "Typography by Content Voice" in `./references/libraries.md`
**For CSS/layout patterns and SVG connectors**, read `./references/css-patterns.md`.
**For pages with 4+ sections** (reviews, recaps, dashboards), also read `./references/responsive-nav.md` for section navigation with sticky sidebar TOC on desktop and horizontal scrollable bar on mobile.
**Choosing a rendering approach:**
| Content type | Approach | Why |
|---|---|---|
| Architecture (text-heavy) | CSS Grid cards + flow arrows | Rich card content (descriptions, code, tool lists) needs CSS control |
| Architecture (topology-focused) | **Mermaid** | Visible connections between components need automatic edge routing |
| Flowchart / pipeline | **Mermaid** | Automatic node positioning and edge routing |
| Sequence diagram | **Mermaid** | Lifelines, messages, and activation boxes need automatic layout |
| Data flow | **Mermaid** with edge labels | Connections and data descriptions need automatic edge routing |
| ER / schema diagram | **Mermaid** | Relationship lines between many entities need auto-routing |
| State machine | **Mermaid** | State transitions with labeled edges need automatic layout |
| Mind map | **Mermaid** | Hierarchical branching needs automatic positioning |
| Class diagram | **Mermaid** | Inheritance, composition, aggregation lines with automatic routing |
| C4 architecture | **Mermaid** | Use `graph TD` + `subgraph` for C4 (not native `C4Context` — it ignores themes) |
| Data table | HTML `<table>` | Semantic markup, accessibility, copy-paste behavior |
| Timeline | CSS (central line + cards) | Simple linear layout doesn't need a layout engine |
| Dashboard | CSS Grid + Chart.js | Card grid with embedded charts |
**Mermaid theming:** Always use `theme: 'base'` with custom `themeVariables` so colors match your page palette. Use `layout: 'elk'` for complex graphs (requires the `@mermaid-js/layout-elk` package — see `./references/libraries.md` for the CDN import). Override Mermaid's SVG classes with CSS for pixel-perfect control. See `./references/libraries.md` for full theming guide.
**Mermaid containers:** Always center Mermaid diagrams with `display: flex; justify-content: center;`. Add zoom controls (+/−/reset/expand) to every `.mermaid-wrap` container. Include the click-to-expand JavaScript so clicking the diagram (or the ⛶ button) opens it full-size in a new tab.
**Mermaid scaling:** Diagrams with 10+ nodes render too small by default. For 10-12 nodes, increase `fontSize` in themeVariables to 18-20px and set `INITIAL_ZOOM` to 1.5-1.6. For 15+ elements, don't try to scale — use the hybrid pattern instead (simple Mermaid overview + CSS Grid cards). See "Architecture / System Diagrams" below.
**Mermaid layout direction:** Prefer `flowchart TD` (top-down) over `flowchart LR` (left-to-right) for complex diagrams. LR spreads horizontally and makes labels unreadable when there are many nodes. Use LR only for simple 3-4 node linear flows. See `./references/libraries.md` "Layout Direction: TD vs LR".
**Mermaid line breaks in flowchart labels:** Use `<br/>` inside quoted labels. Never use escaped newlines like `\n` (Mermaid renders them as literal text in HTML output). Example: `A["Copilot Backend<br/>/api + /api/voicebot"]`.
**Mermaid CSS class collision constraint:** Never define `.node` as a page-level CSS class. Mermaid.js uses `.node` internally on SVG `<g>` elements with `transform: translate(x, y)` for positioning. Page-level `.node` styles (hover transforms, box-shadows) leak into diagrams and break layout. Use the namespaced `.ve-card` class for card components instead. The only safe way to style Mermaid's `.node` is scoped under `.mermaid` (e.g., `.mermaid .node rect`).
**AI-generated illustrations (optional).** If [surf-cli](https://github.com/nicobailon/surf-cli) is available, you can generate images via Gemini and embed them in the page for creative, illustrative, explanatory, educational, or decorative purposes. Check availability with `which surf`. If available:
```bash
# Generate to a temp file (use --aspect-ratio for control)
surf gemini "descriptive prompt" --generate-image /tmp/ve-img.png --aspect-ratio 16:9
# Base64 encode for self-containment (macOS)
IMG=$(base64 -i /tmp/ve-img.png)
# Linux: IMG=$(base64 -w 0 /tmp/ve-img.png)
# Embed in HTML and clean up
# <img src="data:image/png;base64,${IMG}" alt="descriptive alt text">
rm /tmp/ve-img.png
```
See `./references/css-patterns.md` for image container styles (hero banners, inline illustrations, captions).
**When to use:** Hero banners that establish the page's visual tone. Conceptual illustrations for abstract systems that Mermaid can't express (physical infrastructure, user journeys, mental models). Educational diagrams that benefit from artistic or photorealistic rendering. Decorative accents that reinforce the aesthetic.
**When to skip:** Anything Mermaid or CSS handles well. Generic decoration that doesn't convey meaning. Data-heavy pages where images would distract. Always degrade gracefully — if surf isn't available, skip images without erroring. The page should stand on its own with CSS and typography alone.
**Prompt craft:** Match the image to the page's palette and aesthetic direction. Specify the style (3D render, technical illustration, watercolor, isometric, flat vector, etc.) and mention dominant colors from your CSS variables. Use `--aspect-ratio 16:9` for hero banners, `--aspect-ratio 1:1` for inline illustrations. Keep prompts specific — "isometric illustration of a message queue with cyan nodes on dark navy background" beats "a diagram of a queue."
### 3. Style
Apply these principles to every diagram:
**Typography is the diagram.** Pick a distinctive font pairing from the list in `./references/libraries.md`. Every page should use a different pairing from recent generations.
**Forbidden as `--font-body`:** Inter, Roboto, Arial, Helvetica, system-ui alone. These are AI slop signals.
**Good pairings (use these):**
- DM Sans + Fira Code (technical, precise)
- Instrument Serif + JetBrains Mono (editorial, refined)
- IBM Plex Sans + IBM Plex Mono (reliable, readable)
- Bricolage Grotesque + Fragment Mono (bold, characterful)
- Plus Jakarta Sans + Azeret Mono (rounded, approachable)
Load via `<link>` in `<head>`. Include a system font fallback in the `font-family` stack for offline resilience.
**Color tells a story.** Use CSS custom properties for the full palette. Define at minimum: `--bg`, `--surface`, `--border`, `--text`, `--text-dim`, and 3-5 accent colors. Each accent should have a full and a dim variant (for backgrounds). Name variables semantically when possible (`--pipeline-step` not `--blue-3`). Support both themes.
**Forbidden accent colors:** `#8b5cf6` `#7c3aed` `#a78bfa` (indigo/violet), `#d946ef` (fuchsia), the cyan-magenta-pink combination. These are Tailwind defaults that signal zero design intent.
**Good accent palettes (use these):**
- Terracotta + sage (`#c2410c`, `#65a30d`) — warm, earthy
- Teal + slate (`#0891b2`, `#0369a1`) — technical, precise
- Rose + cranberry (`#be123c`, `#881337`) — editorial, refined
- Amber + emerald (`#d97706`, `#059669`) — data-focused
- Deep blue + gold (`#1e3a5f`, `#d4a73a`) — premium, sophisticated
Put your primary aesthetic in `:root` and the alternate in the media query:
```css
/* Light-first (editorial, paper/ink, blueprint): */
:root { /* light values */ }
@media (prefers-color-scheme: dark) { :root { /* dark values */ } }
/* Dark-first (neon, IDE-inspired, terminal): */
:root { /* dark values */ }
@media (prefers-color-scheme: light) { :root { /* light values */ } }
```
**Surfaces whisper, they don't shout.** Build depth through subtle lightness shifts (2-4% between levels), not dramatic color changes. Borders should be low-opacity rgba (`rgba(255,255,255,0.08)` in dark mode, `rgba(0,0,0,0.08)` in light) — visible when you look, invisible when you don't.
**Backgrounds create atmosphere.** Don't use flat solid colors for the page background. Subtle gradients, faint grid patterns via CSS, or gentle radial glows behind focal areas. The background should feel like a space, not a void.
**Visual weight signals importance.** Not every section deserves equal visual treatment. Executive summaries and key metrics should dominate the viewport on load (larger type, more padding, subtle accent-tinted background zone). Reference sections (file maps, dependency lists, decision logs) should be compact and stay out of the way. Use `<details>/<summary>` for sections that are useful but not primary — the collapsible pattern is in `./references/css-patterns.md`.
**Surface depth creates hierarchy.** Vary card depth to signal what matters. Hero sections get elevated shadows and accent-tinted backgrounds (`ve-card--hero` pattern). Body content stays flat (default `.ve-card`). Code blocks and secondary content feel recessed (`ve-card--recessed`). See the depth tiers in `./references/css-patterns.md`. Don't make everything elevated — when everything pops, nothing does.
**Animation earns its place.** Staggered fade-ins on page load are almost always worth it — they guide the eye through the diagram's hierarchy. Mix animation types by role: `fadeUp` for cards, `fadeScale` for KPIs and badges, `drawIn` for SVG connectors, `countUp` for hero numbers. Hover transitions on interactive-feeling elements make the diagram feel alive. Always respect `prefers-reduced-motion`. CSS transitions and keyframes handle most cases. For orchestrated multi-element sequences, anime.js via CDN is available (see `./references/libraries.md`).
**Forbidden animations:**
- Animated glowing box-shadows (`@keyframes glow { box-shadow: 0 0 20px... }`) — this is AI slop
- Pulsing/breathing effects on static content
- Continuous animations that run after page load (except for progress indicators)
Keep animations purposeful: entrance reveals, hover feedback, and user-initiated interactions. Nothing should glow or pulse on its own.
### 4. Deliver
**Output location:** Write to `~/.agent/diagrams/`. Use a descriptive filename based on content: `modem-architecture.html`, `pipeline-flow.html`, `schema-overview.html`. The directory persists across sessions.
**Open in browser:**
- macOS: `open ~/.agent/diagrams/filename.html`
- Linux: `xdg-open ~/.agent/diagrams/filename.html`
**Tell the user** the file path so they can re-open or share it.
## Diagram Types
### Architecture / System Diagrams
Three approaches depending on complexity:
**Simple topology (under 10 elements):** Use Mermaid. A `graph TD` with custom `themeVariables` produces readable diagrams with automatic edge routing.
**Text-heavy overviews (under 15 elements):** CSS Grid with explicit row/column placement. Sections as rounded cards with colored borders and monospace labels. Vertical flow arrows between sections. The reference template at `./templates/architecture.html` demonstrates this pattern. Use when cards need descriptions, code references, tool lists, or other rich content that Mermaid nodes can't hold.
**Complex architectures (15+ elements):** Use the **hybrid pattern** — a simple Mermaid overview (5-8 nodes showing module relationships) followed by detailed CSS Grid cards for each module's internals. This gives you visual topology AND readable details. The overview diagram uses module names with `<small>` tags for key function names. The cards below show full function lists with new/modified badges. Never try to cram 15+ elements into a single Mermaid diagram — it will render unreadably small even with zoom controls.
### Flowcharts / Pipelines
**Use Mermaid.** Automatic node positioning and edge routing produces proper diagrams with connecting lines, decision diamonds, and parallel branches — dramatically better than CSS flexbox with arrow characters. Prefer `graph TD` (top-down); use `graph LR` only for simple 3-4 node linear flows. Color-code node types with Mermaid's `classDef` or rely on `themeVariables` for automatic styling.
### Sequence Diagrams
**Use Mermaid.** Lifelines, messages, activation boxes, notes, and loops all need automatic layout. Use Mermaid's `sequenceDiagram` syntax. Style actors and messages via CSS overrides on `.actor`, `.messageText`, `.activation` classes.
### Data Flow Diagrams
**Use Mermaid.** Data flow diagrams emphasize connections over boxes — exactly what Mermaid excels at. Use `graph TD` (or `graph LR` for simple linear flows) with edge labels for data descriptions. Thicker, colored edges for primary flows. Source/sink nodes styled differently from transform nodes via Mermaid's `classDef`.
### Schema / ER Diagrams
**Use Mermaid.** Relationship lines between entities need automatic routing. Use Mermaid's `erDiagram` syntax with entity attributes. Style via `themeVariables` and CSS overrides on `.er.entityBox` and `.er.relationshipLine`.
### State Machines / Decision Trees
**Use Mermaid.** Use `stateDiagram-v2` for states with labeled transitions. Supports nested states, forks, joins, and notes. Decision trees can use `graph TD` with diamond decision nodes.
**`stateDiagram-v2` label caveat:** Transition labels have a strict parser — colons, parentheses, `<br/>`, HTML entities, and most special characters cause silent parse failures ("Syntax error in text"). If your labels need any of these (e.g., `cancel()`, `curate: true`, multi-line labels), use `flowchart TD` instead with rounded nodes and quoted edge labels (`|"label text"|`). Flowcharts handle all special characters and support `<br/>` for line breaks. Reserve `stateDiagram-v2` for simple single-word or plain-text labels.
### Mind Maps / Hierarchical Breakdowns
**Use Mermaid.** Use `mindmap` syntax for hierarchical branching from a root node. Mermaid handles the radial layout automatically. Style with `themeVariables` to control node colors at each depth level.
### Class Diagrams
**Use Mermaid.** Use `classDiagram` syntax for domain modeling, OOP design, and entity relationships with typed properties and methods. Supports relationships: association (`-->`), composition (`*--`), aggregation (`o--`), and inheritance (`<|--`). Add multiplicity labels (e.g., `"1" --> "*"`) and abstract/interface markers (`<<interface>>`, `<<abstract>>`). For simple entity boxes without OOP semantics (no methods, no inheritance), prefer `erDiagram` instead — it produces cleaner output for pure data modeling.
### C4 Architecture Diagrams
**Use Mermaid flowchart syntax — NOT native C4.** Use `graph TD` with `subgraph` blocks for C4 boundaries. Native `C4Context` hardcodes sharp corners, its own font, blue icons, and inline SVG colors that ignore `themeVariables` — it always clashes with custom palettes.
**Flowchart-as-C4 pattern:** Persons → rounded nodes `(("Name"))`, systems → rectangles `["Name"]`, databases → cylinders `[("Name")]`, boundaries → `subgraph` blocks, relationships → labeled arrows `-->|"protocol"|`. Use `classDef` + `:::className` to visually differentiate external systems (e.g., dashed borders). This inherits `themeVariables`, `fontFamily`, and CSS overrides like every other Mermaid diagram.
### Data Tables / Comparisons / Audits
Use a real `<table>` element — not CSS Grid pretending to be a table. Tables get accessibility, copy-paste behavior, and column alignment for free. The reference template at `./templates/data-table.html` demonstrates all patterns below.
**Use proactively.** Any time you'd render an ASCII box-drawing table in the terminal, generate an HTML table instead. This includes: requirement audits (request vs plan), feature comparisons, status reports, configuration matrices, test result summaries, dependency lists, permission tables, API endpoint inventories — any structured rows and columns.
Layout patterns:
- Sticky `<thead>` so headers stay visible when scrolling long tables
- Alternating row backgrounds via `tr:nth-child(even)` (subtle, 2-3% lightness shift)
- First column optionally sticky for wide tables with horizontal scroll
- Responsive wrapper with `overflow-x: auto` for tables wider than the viewport
- Column width hints via `<colgroup>` or `th` widths — let text-heavy columns breathe
- Row hover highlight for scanability
Status indicators (use styled `<span>` elements, never emoji):
- Match/pass/yes: colored dot or checkmark with green background
- Gap/fail/no: colored dot or cross with red background
- Partial/warning: amber indicator
- Neutral/info: dim text or muted badge
Cell content:
- Wrap long text naturally — don't truncate or force single-line
- Use `<code>` for technical references within cells
- Secondary detail text in `<small>` with dimmed color
- Keep numeric columns right-aligned with `tabular-nums`
### Timeline / Roadmap Views
Vertical or horizontal timeline with a central line (CSS pseudo-element). Phase markers as circles on the line. Content cards branching left/right (alternating) or all to one side. Date labels on the line. Color progression from past (muted) to future (vivid).
### Dashboard / Metrics Overview
Card grid layout. Hero numbers large and prominent. Sparklines via inline SVG `<polyline>`. Progress bars via CSS `linear-gradient` on a div. For real charts (bar, line, pie), use **Chart.js via CDN** (see `./references/libraries.md`). KPI cards with trend indicators (up/down arrows, percentage deltas).
### Implementation Plans
For visualizing implementation plans, extension designs, or feature specifications. The goal is **understanding the approach**, not reading the full source code.
**Don't dump full files.** Displaying entire source files inline overwhelms the page and defeats the purpose of a visual explanation. Instead:
- Show **file structure with descriptions** — list functions/exports with one-line explanations
- Show **key snippets only** — the 5-10 lines that illustrate the core logic
- Use **collapsible sections** for full code if truly needed
**Code blocks require explicit formatting.** Without `white-space: pre-wrap`, code runs together into an unreadable wall. See the "Code Blocks" section in `./references/css-patterns.md` for the correct pattern.
**Structure for implementation plans:**
1. Overview/purpose (what problem does this solve?)
2. Flow diagram (Mermaid or CSS cards)
3. File structure with descriptions (not full code)
4. Key implementation details (snippets)
5. API/interface summary
6. Usage examples
### Documentation (READMEs, Library Docs, API References)
When visualizing documentation, extract structure into visual elements:
| Content | Visual Treatment |
|---------|------------------|
| Features | Card grid (2-3 columns) |
| Install/setup steps | Numbered cards or vertical flow |
| API endpoints/commands | Table with sticky header |
| Config options | Table |
| Architecture | Mermaid diagram or CSS card layout |
| Comparisons | Side-by-side panels or table |
| Warnings/notes | Callout boxes |
Don't just format the prose — transform it. A feature list becomes a card grid. Install steps become a numbered flow. An API reference becomes a table.
### Prose Accent Elements
Use these sparingly within visual pages to highlight key points or provide breathing room. See "Prose Page Elements" in `./references/css-patterns.md` for CSS patterns.
- **Lead paragraph** — larger intro text to set context before diving into cards/grids
- **Pull quote** — highlight a key insight; one per page maximum
- **Callout box** — warnings, tips, important notes
- **Section divider** — visual break between major sections
**When to use:** A visual page explaining an essay might use a lead paragraph for the thesis, then cards for key arguments. A README visualization might use callout boxes for warnings but otherwise stay card/table-focused.
## Slide Deck Mode
An alternative output format for presenting content as a magazine-quality slide presentation instead of a scrollable page. **Opt-in only** — the agent generates slides when the user invokes `/generate-slides`, passes `--slides` to an existing prompt (e.g., `/diff-review --slides`), or explicitly asks for a slide deck. Never auto-select slide format.
**Before generating slides**, read `./references/slide-patterns.md` (engine CSS, slide types, transitions, nav chrome, presets) and `./templates/slide-deck.html` (reference template showing all 10 types). Also read `./references/css-patterns.md` for shared patterns and `./references/libraries.md` for Mermaid/Chart.js theming.
**Slides are not pages reformatted.** They're a different medium. Each slide is exactly one viewport tall (100dvh) with no scrolling. Typography is 2–3× larger. Compositions are bolder. The agent composes a narrative arc (impact → context → deep dive → resolution) rather than mechanically paginating the source.
**Content completeness.** Changing the medium does not mean dropping content. Follow the "Planning a Deck from a Source Document" process in `slide-patterns.md` before writing any HTML: inventory the source, map every item to slides, verify coverage. Every section, decision, data point, specification, and collapsible detail from the source must appear in the deck. If a plan has 7 sections, the deck covers all 7. If there are 6 decisions, present all 6 — not the 2 that fit on one slide. Collapsible details in the source become their own slides. Add more slides rather than cutting content. A 22-slide deck that covers everything beats a 13-slide deck that looks polished but is missing 40% of the source.
**Slide types (10):** Title, Section Divider, Content, Split, Diagram, Dashboard, Table, Code, Quote, Full-Bleed. Each has a defined layout in `slide-patterns.md`. Content that exceeds a slide's density limit splits across multiple slides — never scrolls within a slide.
**Visual richness:** Check `which surf` at the start. If surf-cli is available, generate 2–4 images (title slide background, full-bleed background, optional content illustrations) before writing HTML — see the Proactive Imagery section in `slide-patterns.md` for the workflow. Also use SVG decorative accents, per-slide background gradients, inline sparklines, and small Mermaid diagrams. Visual-first, text-second.
**Compositional variety:** Consecutive slides must vary spatial approach — centered, left-heavy, right-heavy, split, edge-aligned, full-bleed. Three centered slides in a row means push one off-axis.
**Curated presets:** Four slide-specific presets as starting points (Midnight Editorial, Warm Signal, Terminal Mono, Swiss Clean) plus the existing 8 aesthetic directions adapted for slides. Pick one and commit. See `slide-patterns.md` for preset CSS values.
**`--slides` flag on existing prompts:** When a user passes `--slides` to `/diff-review`, `/plan-review`, `/project-recap`, or other prompts, the agent gathers data using the prompt's normal data-gathering instructions, then presents the content as a slide deck instead of a scrollable page. The slide version tells the same story with different structure and pacing — but the same breadth of coverage. Don't use the slide format as an excuse to summarize or skip sections that the scrollable version would have included.
## File Structure
Every diagram is a single self-contained `.html` file. No external assets except CDN links (fonts, optional libraries). Structure:
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Descriptive Title</title>
<link href="https://fonts.googleapis.com/css2?family=...&display=swap" rel="stylesheet">
<style>
/* CSS custom properties, theme, layout, components — all inline */
</style>
</head>
<body>
<!-- Semantic HTML: sections, headings, lists, tables, inline SVG -->
<!-- No script needed for static CSS-only diagrams -->
<!-- Optional: <script> for Mermaid, Chart.js, or anime.js when used -->
</body>
</html>
```
## Sharing Pages
Share visual explainer pages instantly via Vercel. No account or authentication required.
**Usage:**
```bash
bash {{skill_dir}}/scripts/share.sh <html-file>
```
**Example:**
```bash
bash {{skill_dir}}/scripts/share.sh ~/.agent/diagrams/my-diagram.html
# Output:
# ✓ Shared successfully!
# Live URL: https://skill-deploy-abc123.vercel.app
# Claim URL: https://vercel.com/claim-deployment?code=...
```
**How it works:**
1. Copies HTML file to temp directory as `index.html`
2. Deploys via the vercel-deploy skill (zero-auth claimable deployment)
3. URL is live immediately — works in any browser
**Requirements:**
- vercel-deploy skill (should be pre-installed; if not: `pi install npm:vercel-deploy`)
**Notes:**
- Deployments are public — anyone with the URL can view
- Preview deployments have configurable retention (default: 30 days)
- Claim URL lets you transfer the deployment to your Vercel account
See `./commands/share.md` for the `/share` command template.
## Quality Checks
Before delivering, verify:
- **The squint test**: Blur your eyes. Can you still perceive hierarchy? Are sections visually distinct?
- **The swap test**: Would replacing your fonts and colors with a generic dark theme make this indistinguishable from a template? If yes, push the aesthetic further.
- **Both themes**: Toggle your OS between light and dark mode. Both should look intentional, not broken.
- **Information completeness**: Does the diagram actually convey what the user asked for? Pretty but incomplete is a failure.
- **No overflow**: Resize the browser to different widths. No content should clip or escape its container. Every grid and flex child needs `min-width: 0`. Side-by-side panels need `overflow-wrap: break-word`. Never use `display: flex` on `<li>` for marker characters — it creates anonymous flex items that can't shrink, causing lines with many inline `<code>` badges to overflow. Use absolute positioning for markers instead. See the Overflow Protection section in `./references/css-patterns.md`.
- **Mermaid zoom controls**: Every `.mermaid-wrap` container must have zoom controls (+/−/reset/expand buttons), Ctrl/Cmd+scroll zoom, click-and-drag panning, and click-to-expand (clicking without dragging opens the diagram full-size in a new tab). The expand button (⛶) provides the same functionality. See `./references/css-patterns.md` for the full pattern including the `openMermaidInNewTab()` function.
- **File opens cleanly**: No console errors, no broken font loads, no layout shifts.
## Anti-Patterns (AI Slop)
These patterns are explicitly forbidden. They signal "AI-generated template" and undermine the skill's purpose of producing distinctive, high-quality diagrams. Review every generated page against this list.
### Typography
**Forbidden fonts as primary `--font-body`:**
- Inter — the single most overused AI default
- Roboto, Arial, Helvetica — generic system fallbacks promoted to primary
- system-ui, sans-serif alone — no character, no intent
**Required:** Pick from the font pairings in `./references/libraries.md`. Every generation should use a different pairing from the last.
### Color Palette
**Forbidden accent colors:**
- Indigo-500/violet-500 (`#8b5cf6`, `#7c3aed`, `#a78bfa`) — Tailwind's default purple range
- The cyan + magenta + pink neon gradient combination (`#06b6d4` → `#d946ef` → `#f472b6`)
- Any palette that could be described as "Tailwind defaults with purple/pink/cyan accents"
**Forbidden color effects:**
- Gradient text on headings (`background: linear-gradient(...); background-clip: text;`) — this screams AI-generated
- Animated glowing box-shadows on cards (`box-shadow: 0 0 20px var(--glow); animation: glow 2s...`)
- Multiple overlapping radial glows in accent colors creating a "neon haze"
**Required:** Build palettes from the reference templates (terracotta/sage, teal/cyan, rose/cranberry, slate/blue) or derive from real IDE themes (Dracula, Nord, Solarized, Gruvbox, Catppuccin). Accents should feel intentional, not default.
### Section Headers
**Forbidden:**
- Emoji icons in section headers (🏗️, ⚙️, 📁, 💻, 📅, 🔗, ⚡, 🔧, 📦, 🚀, etc.)
- Section headers that all use the same icon-in-rounded-box pattern
**Required:** Use styled monospace labels with colored dot indicators (see `.section-label` in templates), numbered badges (`section__num` pattern), or asymmetric section dividers. If an icon is genuinely needed, use an inline SVG that matches the palette — not emoji.
### Layout & Hierarchy
**Forbidden:**
- Perfectly centered everything with uniform padding
- All cards styled identically with the same border-radius, shadow, and spacing
- Every section getting equal visual treatment — no hero/primary vs. secondary distinction
- Symmetric layouts where left and right halves mirror each other
**Required:** Vary visual weight. Hero sections should dominate (larger type, more padding, accent-tinted background). Reference sections should feel compact. Use the depth tiers (hero → elevated → default → recessed). Asymmetric layouts create interest.
### Template Patterns
**Forbidden:**
- Three-dot window chrome (red/yellow/green dots) on code blocks — this is a cliché
- KPI cards where every metric has identical gradient text treatment
- "Neon Dashboard" as an aesthetic choice — it always produces generic results
- Gradient meshes with pink/purple/cyan blobs in the background
**Required:** Code blocks use a simple header with filename or language label. KPI cards vary by importance — hero numbers for the primary metric, subdued treatment for supporting metrics. Pick aesthetics with natural constraints: Blueprint (must feel technical/precise), Editorial (must have generous whitespace and serif typography), Paper/ink (must feel warm and informal).
### The Slop Test
Before delivering, apply this test: **Would a developer looking at this page immediately think "AI generated this"?** The telltale signs:
1. Inter or Roboto font with purple/violet gradient accents
2. Every heading has `background-clip: text` gradient
3. Emoji icons leading every section
4. Glowing cards with animated shadows
5. Cyan-magenta-pink color scheme on dark background
6. Perfectly uniform card grid with no visual hierarchy
7. Three-dot code block chrome
If two or more of these are present, the page is slop. Regenerate with a different aesthetic direction — Editorial, Blueprint, Paper/ink, or a specific IDE theme. These constrained aesthetics are harder to mess up because they have specific visual requirements that prevent defaulting to generic patterns.
# Changelog
## [0.5.0] - 2026-03-04
### Class Diagram and C4 Architecture Support
- Added `classDiagram` guidance for OOP design and domain modeling
- Documented relationships: association, composition, aggregation, inheritance
- Added C4 architecture support using `graph TD` + `subgraph` (not native `C4Context` which ignores themes)
- Added `.dir-tree` CSS pattern for file structures with tree connectors
- Added quick-reference table for choosing Mermaid diagram types
### Claude Code Plugin Support
- Added `.claude-plugin/plugin.json` manifest for Claude Code plugin installation
- Renamed `prompts/` to `commands/` (compatible with both pi and Claude Code)
- Claude Code: `claude /plugin install https://github.com/nicobailon/visual-explainer`
- Note: Claude Code namespaces commands as `/visual-explainer:command-name`
### OpenAI Codex Support
- Added install instructions for OpenAI Codex to README
- Uses `~/.agents/skills` and `~/.agents/commands` paths
### Share Command
- New `/share` prompt and `scripts/share.sh` for instant sharing of visual explainer pages
- Uses vercel-deploy skill — no account or authentication required
- Zero-friction: just `bash scripts/share.sh mypage.html` → live URL in seconds
- Returns claimable deployment (can transfer to your Vercel account later)
- JSON output for programmatic use
### Bug Fixes
- Fixed pi skill loading: scoped `pi.skills` to `./SKILL.md` instead of `./` (was trying to load README.md and CHANGELOG.md as skills)
- Fixed Mermaid line breaks: use `<br/>` instead of `\n` in flowchart labels (renders as literal text otherwise)
- Fixed `mermaid-flowchart.html` to match documented pattern: moved flex centering from `.mermaid-wrap .mermaid` to `.mermaid-wrap`, added `min-height: 400px`
- Fixed `share.sh` to properly capture and display deployment errors (was silently exiting due to `set -e`)
## [0.4.5] - 2026-03-04
### Click-to-Expand Mermaid Diagrams
- Clicking anywhere on a Mermaid diagram (without dragging) opens it full-size in a new browser tab
- Added expand button (⛶) to zoom controls for discoverability
- New `openMermaidInNewTab()` and `openDiagramFullscreen()` functions in the Mermaid JavaScript pattern
- Click detection distinguishes quick clicks from drag-to-pan (5px movement threshold, 300ms time threshold)
- Full-size view preserves the page's background color for visual consistency
- Updated all templates (`mermaid-flowchart.html`, `slide-deck.html`) with new pattern
- Updated `css-patterns.md` and `slide-patterns.md` documentation
### Bug Fixes
- Removed unused `text` variable in `openMermaidInNewTab()` function
- Removed unused `e` parameter in mouseup handlers
- Fixed inconsistent zoom range limits (standardized to 0.5x–5x across all files)
- Removed dead CSS `.mermaid-wrap.is-zoomed` rule (class was never applied by JavaScript)
- Removed dead CSS `transition: transform` on `.mermaid` (zoom property is not animatable)
- Added missing `cursor: grab` to base `.mermaid-wrap` selector in templates
- Added missing flex centering (`display: flex; justify-content: center; align-items: center`) to `.mermaid-wrap` in `slide-deck.html`
- Updated `SKILL.md` to explicitly mention the click-to-expand feature and expand button so agents include it when generating pages
- Updated all prompt templates (`diff-review.md`, `plan-review.md`, `project-recap.md`, `generate-visual-plan.md`) to specify the expand button and click-to-expand functionality for Mermaid diagrams
## [0.4.3] - 2026-03-01
### Mermaid Zoom and Positioning Fixes
- **Fixed zoom clipping**: Replaced `transform: scale()` with CSS `zoom` property. Transform only changes visual appearance — content expanding upward/leftward goes into negative space which can't be scrolled to. Zoom changes actual layout size, so overflow scrolls normally in all directions.
- **Fixed vertical centering**: Changed `align-items: flex-start` to `align-items: center` so diagrams are centered both horizontally and vertically in their container.
- **Added initial zoom**: Complex diagrams can start at zoom > 1 (e.g., 1.4x) for better readability while keeping zoom controls functional.
- **Added min-height**: Containers now have `min-height: 400px` to prevent vertical flowcharts from compressing into unreadable thumbnails.
- Removed unnecessary `.mermaid-inner` wrapper — no longer needed with zoom-based approach.
- Updated JavaScript to use `INITIAL_ZOOM` constant for consistent reset behavior.
- Updated "Scaling Small Diagrams" section to use `zoom` instead of `transform: scale()` for consistency.
## [0.4.4] - 2026-03-02
### Hybrid Architecture Pattern
- New pattern for complex architectures (15+ elements): simple Mermaid overview (5-8 nodes) + CSS Grid cards for details
- Updated "Architecture / System Diagrams" section in SKILL.md with three-tier approach based on complexity
- Reduced max Mermaid node count from 15-20 to 10-12 in `libraries.md`
- Updated Mermaid scaling guidance to recommend hybrid pattern over scaling tricks for complex diagrams
## [0.4.2] - 2026-03-01
### Link Styling
- New "Link Styling" section in `css-patterns.md` — never rely on browser default link colors; use accent colors with sufficient contrast
## [0.4.1] - 2026-03-01
### Mermaid Layout Direction
- New "Layout Direction: TD vs LR" section in `libraries.md`
- Prefer `flowchart TD` (top-down) over `flowchart LR` (left-to-right) for complex diagrams
- LR spreads horizontally and makes labels unreadable with many nodes
- Rule: use TD for 5+ nodes or any branching; LR only for simple 3-4 node linear flows
### Documentation
- Simplified README: trimmed Usage section, consolidated Install, added Slide Deck Mode section
- Added `/generate-visual-plan` to command table
## [0.4.0] - 2026-02-28
### New Prompt Template
- `/generate-visual-plan` — generate visual implementation plans for features and extensions. Produces editorial/blueprint-style HTML pages with problem comparison panels, state machine diagrams, code snippets, edge case tables, and implementation notes. Designed for documenting feature specs before implementation.
### Prose Accent Patterns
Added patterns for use as accent elements within visual pages.
**`css-patterns.md`** — New "Prose Page Elements" section:
- Body text settings (font-size, line-height, max-width for comfortable reading)
- Lead paragraph patterns (larger size, drop cap variants)
- Pull quotes (border-left, centered with quotation mark)
- Section dividers (horizontal rule, ornamental)
- Article hero patterns (centered, editorial)
- Author byline pattern
- Prose-specific anti-patterns
**`libraries.md`** — New "Typography by Content Voice" section:
- Font recommendations by content type (literary, technical, bold, minimal)
- Special mention of Literata for screen reading
**`SKILL.md`** — New sections:
- "Prose Accent Elements" — when to use lead paragraphs, pull quotes, callouts
- "Documentation" — content-to-visual mapping (features→cards, steps→flows, APIs→tables)
### Overflow Fix: List Markers in Bordered Containers
- `css-patterns.md`: New section "List markers overlapping container borders" with three solutions
- Rule of thumb: use `list-style-position: inside` or `padding-left: 2em` for lists in bordered containers
### Mermaid Fixes
- Centering: narrow vertical flowcharts must be centered, not left-aligned
- Scaling: complex diagrams with 10+ nodes render too small — increase fontSize to 18-20px or use CSS scale transform
- Special characters: node labels starting with `/`, `\`, `(`, `{` must be quoted to avoid shape syntax conflicts
- New "Scaling Small Diagrams" section in css-patterns.md
- New "Node Label Special Characters" section in libraries.md
### Code Block Patterns
- `css-patterns.md`: New "Code Blocks" section with:
- Basic pattern with `white-space: pre-wrap` (critical for preserving line breaks)
- File header pattern for displaying code with filename
- Implementation plan guidance: don't dump full files, show structure instead
- `SKILL.md`: New "Implementation Plans" section with structure guidance
## [0.3.0] - 2026-02-26
### Anti-Slop Guardrails
- Added explicit "Anti-Patterns (AI Slop)" section to SKILL.md with forbidden patterns
- Removed "Neon dashboard" and "Gradient mesh" from allowed aesthetics — they always produce generic output
- Categorized aesthetics as "Constrained" (safer) vs "Flexible" (use with caution)
- Explicit forbidden fonts: Inter, Roboto, Arial, Helvetica, system-ui as primary
- Explicit forbidden colors: indigo/violet range (`#8b5cf6`, `#7c3aed`, `#a78bfa`), cyan-magenta-pink combination
- Explicit forbidden effects: gradient text on headings, animated glowing box-shadows, emoji section headers
- Added "The Slop Test" — 7-point checklist to catch AI-generated patterns before delivery
- Strengthened typography guidance with 5 explicit good pairings to use
- Strengthened color guidance with 5 explicit good palettes to use
- Referenced `websocket-implementation-plan.html` as positive example of Blueprint aesthetic
### Template Fixes
- Replaced violet secondary colors in `mermaid-flowchart.html` with sky blue to match anti-slop guidelines
- Updated Mermaid themeVariables example in `libraries.md` to use teal/slate palette instead of violet
## [0.2.0] - 2026-02-25
### Slide Deck Mode
- New output format: magazine-quality slide deck presentations as self-contained HTML files
- 10 slide types: Title, Section Divider, Content, Split, Diagram, Dashboard, Table, Code, Quote, Full-Bleed
- SlideEngine JS: keyboard/touch/wheel navigation, progress bar, nav dots, slide counter, keyboard hints with auto-fade
- Cinematic transitions: fade + translateY + scale on slide entrance, staggered child reveals via IntersectionObserver
- 4 curated presets: Midnight Editorial, Warm Signal, Terminal Mono, Swiss Clean (each with full light/dark palette)
- Event delegation: Mermaid zoom, scrollable code/tables don't trigger slide navigation
- Responsive height breakpoints (700px, 600px, 500px) for projection and small viewports
- Typography scale 2–3× larger than scrollable pages (80–120px display, 28–48px headings, 16–24px body)
- Per-slide background variation, SVG decorative accents, compositional variety rules
- Proactive imagery: surf-cli integration for title/full-bleed backgrounds, inline sparklines, mini-charts
- New `/generate-slides` prompt template; existing prompts support `--slides` flag via SKILL.md workflow
- Unified `autoFit()` post-render function: auto-scales Mermaid SVGs, KPI values, and long blockquotes to fit their containers
- Fix Mermaid diagrams rendering tiny in slide containers (flex shrink-wrap + inline max-width)
- Fix KPI card overflow for text values (white-space + transform scale)
- Fix quote slides with long text (proportional font-size reduction)
### Files
- `references/slide-patterns.md` — slide engine CSS, all 10 type layouts, transitions, nav chrome, content density limits, presets
- `templates/slide-deck.html` — reference template demonstrating all 10 types in Midnight Editorial preset
- `prompts/generate-slides.md` — slash command for generating slide decks
- `SKILL.md` — new "Slide Deck Mode" section with slide routing, `--slides` flag detection, visual richness guidance
## [0.1.4] - 2026-02-24
- Removed Mermaid `handDrawn` mode — Rough.js hachure fills are hardcoded and render unreadable diagonal scribbles inside nodes with no user-facing override. All diagrams now use `look: 'classic'` with custom `themeVariables` for visual distinction.
- Added `package.json` for `pi install` support — installs the skill and all slash commands in one step instead of `git clone` + manual `cp`
## [0.1.3] - 2026-02-24
- Extended `classDef` color warning to also cover per-node `style` directives — both hardcode text color that breaks in the opposite color scheme
- Renamed `.node` card classes to `.ve-card` to fix CSS collision with Mermaid's internal `.node` class that broke diagram layout (PR #7)
## [0.1.2] - 2026-02-19
- Added sequence diagram syntax guidance to "Writing Valid Mermaid" — curly braces, brackets, and ampersands in message labels silently break rendering
## [0.1.1] - 2026-02-19
- Prompts no longer require the `pi-prompt-template-model` extension — each prompt now explicitly loads the skill itself
- Added "Writing Valid Mermaid" section to `libraries.md` (quoting special chars, simple IDs, max node count, arrow styles, pipe escaping)
- Fixed mobile scroll offset in `responsive-nav.md` — section headings now clear the sticky nav bar via `scroll-margin-top`
- Added video preview to README
## [0.1.0] - 2026-02-16
Initial release.
### Skill
- Core workflow: Think (pick aesthetic) → Structure (read template) → Style (apply design) → Deliver (write + open)
- 11 diagram types with rendering approach routing (Mermaid, CSS Grid, HTML tables, Chart.js)
- 9 aesthetic directions (monochrome terminal, editorial, blueprint, neon, paper/ink, sketch, IDE-inspired, data-dense, gradient mesh)
- Mermaid deep theming with `theme: 'base'` + `themeVariables`, hand-drawn mode, ELK layout
- Zoom controls (buttons, scroll-to-zoom, drag-to-pan) required on all Mermaid containers
- Proactive table rendering — agent generates HTML instead of ASCII for complex tables
- Optional AI-generated illustrations via surf-cli + Gemini Nano Banana Pro
- Both light and dark themes via CSS custom properties and `prefers-color-scheme`
- Quality checks: squint test, swap test, overflow protection, zoom controls verification
### References
- `css-patterns.md` — theme setup, depth tiers, node cards, grid layouts, data tables, status badges, KPI cards, before/after panels, connectors, animations (fadeUp, fadeScale, drawIn, countUp), collapsible sections, overflow protection, generated image containers
- `libraries.md` — Mermaid (CDN, ELK, deep theming, hand-drawn mode, CSS overrides, diagram examples), Chart.js, anime.js, Google Fonts with 13 font pairings
- `responsive-nav.md` — sticky sidebar TOC on desktop, horizontal scrollable bar on mobile, scroll spy
### Templates
- `architecture.html` — CSS Grid card layout, terracotta/sage palette, depth tiers, flow arrows, pipeline with parallel branches
- `mermaid-flowchart.html` — Mermaid flowchart with ELK + handDrawn mode, teal/cyan palette, zoom controls
- `data-table.html` — HTML table with KPI cards, status badges, collapsible details, rose/cranberry palette
### Prompt Templates
- `/generate-web-diagram` — generate a diagram for any topic
- `/diff-review` — visual diff review with architecture comparison, KPI dashboard, code review, decision log
- `/plan-review` — plan vs. codebase with current/planned architecture, risk assessment, understanding gaps
- `/project-recap` — project mental model snapshot for context-switching
- `/fact-check` — verify factual accuracy of review pages and plan docs against actual code
MIT License Copyright (c) 2025 Nico Bailon Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
<p>
<img src="banner.png" alt="visual-explainer" width="1100">
</p>
# visual-explainer
**An agent skill that turns complex terminal output into styled HTML pages you actually want to read.**
[](LICENSE)
Ask your agent to explain a system architecture, review a diff, or compare requirements against a plan. Instead of ASCII art and box-drawing tables, it generates a self-contained HTML page and opens it in your browser.
```
> draw a diagram of our authentication flow
> /diff-review
> /plan-review ~/docs/refactor-plan.md
```
https://github.com/user-attachments/assets/55ebc81b-8732-40f6-a4b1-7c3781aa96ec
## Why
Every coding agent defaults to ASCII art when you ask for a diagram. Box-drawing characters, monospace alignment hacks, text arrows. It works for trivial cases, but anything beyond a 3-box flowchart turns into an unreadable mess.
Tables are worse. Ask the agent to compare 15 requirements against a plan and you get a wall of pipes and dashes that wraps and breaks in the terminal. The data is there but it's painful to read.
This skill fixes that. Real typography, dark/light themes, interactive Mermaid diagrams with zoom and pan. No build step, no dependencies beyond a browser.
## Install
**Pi:**
```bash
pi install https://github.com/nicobailon/visual-explainer
```
**Claude Code (plugin):**
```bash
claude /plugin install https://github.com/nicobailon/visual-explainer
```
Note: Claude Code plugins namespace commands as `/visual-explainer:command-name`.
**OpenAI Codex:**
```bash
git clone https://github.com/nicobailon/visual-explainer.git ~/.agents/skills/visual-explainer
mkdir -p ~/.agents/commands
cp ~/.agents/skills/visual-explainer/commands/*.md ~/.agents/commands/
```
## Commands
| Command | What it does |
|---------|-------------|
| `/generate-web-diagram` | Generate an HTML diagram for any topic |
| `/generate-visual-plan` | Generate a visual implementation plan for a feature or extension |
| `/generate-slides` | Generate a magazine-quality slide deck |
| `/diff-review` | Visual diff review with architecture comparison and code review |
| `/plan-review` | Compare a plan against the codebase with risk assessment |
| `/project-recap` | Mental model snapshot for context-switching back to a project |
| `/fact-check` | Verify accuracy of a document against actual code |
| `/share` | Deploy an HTML page to Vercel and get a live URL |
The agent also kicks in automatically when it's about to dump a complex table in the terminal (4+ rows or 3+ columns) — it renders HTML instead.
## Slide Deck Mode
Any command that produces a scrollable page supports `--slides` to generate a slide deck instead:
```
/diff-review --slides
/project-recap --slides 2w
```
https://github.com/user-attachments/assets/342d3558-5fcf-4fb2-bc03-f0dd5b9e35dc
## How It Works
```
SKILL.md ← workflow + design principles
commands/ ← slash commands (works with pi and Claude Code)
references/ ← agent reads before generating
├── css-patterns.md (layouts, animations, theming)
├── libraries.md (Mermaid, Chart.js, fonts)
├── responsive-nav.md (sticky TOC for multi-section pages)
└── slide-patterns.md (slide engine, transitions, presets)
templates/ ← reference templates with different palettes
├── architecture.html
├── mermaid-flowchart.html
├── data-table.html
└── slide-deck.html
↓
~/.agent/diagrams/filename.html → opens in browser
```
The skill routes to the right approach automatically: Mermaid for flowcharts and diagrams, CSS Grid for architecture overviews, HTML tables for data, Chart.js for dashboards.
## Limitations
- Requires a browser to view
- Switching OS theme requires a page refresh for Mermaid SVGs
- Results vary by model capability
## Credits
Borrows ideas from [Anthropic's frontend-design skill](https://github.com/anthropics/skills) and [interface-design](https://github.com/Dammyjay93/interface-design).
## License
MIT
{
"name": "visual-explainer",
"version": "0.5.0",
"description": "Agent skill that generates beautiful HTML pages for diagrams, diff reviews, plan reviews, and data tables",
"keywords": [
"pi-package"
],
"license": "MIT",
"pi": {
"skills": [
"./SKILL.md"
],
"prompts": [
"./commands"
]
}
}
# CSS Patterns for Diagrams
Reusable patterns for layout, connectors, theming, and visual effects in self-contained HTML diagrams.
## Theme Setup
Always define both light and dark palettes via custom properties. Start with whichever fits the chosen aesthetic, ensure both work.
```css
:root {
--font-body: 'Outfit', system-ui, sans-serif;
--font-mono: 'Space Mono', 'SF Mono', Consolas, monospace;
--bg: #f8f9fa;
--surface: #ffffff;
--surface-elevated: #ffffff;
--border: rgba(0, 0, 0, 0.08);
--border-bright: rgba(0, 0, 0, 0.15);
--text: #1a1a2e;
--text-dim: #6b7280;
--accent: #0891b2;
--accent-dim: rgba(8, 145, 178, 0.1);
/* Semantic accents for diagram elements */
--node-a: #0891b2;
--node-a-dim: rgba(8, 145, 178, 0.1);
--node-b: #059669;
--node-b-dim: rgba(5, 150, 105, 0.1);
--node-c: #d97706;
--node-c-dim: rgba(217, 119, 6, 0.1);
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #0d1117;
--surface: #161b22;
--surface-elevated: #1c2333;
--border: rgba(255, 255, 255, 0.06);
--border-bright: rgba(255, 255, 255, 0.12);
--text: #e6edf3;
--text-dim: #8b949e;
--accent: #22d3ee;
--accent-dim: rgba(34, 211, 238, 0.12);
--node-a: #22d3ee;
--node-a-dim: rgba(34, 211, 238, 0.12);
--node-b: #34d399;
--node-b-dim: rgba(52, 211, 153, 0.12);
--node-c: #fbbf24;
--node-c-dim: rgba(251, 191, 36, 0.12);
}
}
```
## Background Atmosphere
Flat backgrounds feel dead. Use subtle gradients or patterns.
```css
/* Radial glow behind focal area */
body {
background: var(--bg);
background-image: radial-gradient(ellipse at 50% 0%, var(--accent-dim) 0%, transparent 60%);
}
/* Faint dot grid */
body {
background-color: var(--bg);
background-image: radial-gradient(circle, var(--border) 1px, transparent 1px);
background-size: 24px 24px;
}
/* Diagonal subtle lines */
body {
background-color: var(--bg);
background-image: repeating-linear-gradient(
-45deg, transparent, transparent 40px,
var(--border) 40px, var(--border) 41px
);
}
/* Gradient mesh (pick 2-3 positioned radials) */
body {
background: var(--bg);
background-image:
radial-gradient(at 20% 20%, var(--node-a-dim) 0%, transparent 50%),
radial-gradient(at 80% 60%, var(--node-b-dim) 0%, transparent 50%);
}
```
## Link Styling
**Never rely on browser default link colors.** The default blue (`#0000EE`) has poor contrast on dark backgrounds. Style links with `color: var(--accent)` and keep underlines for discoverability. On dark backgrounds, use bright accents (`#22d3ee`, `#34d399`, `#fbbf24`). On light backgrounds, use deeper tones (`#0891b2`, `#059669`, `#d97706`).
## Section / Card Components
The fundamental building block. A colored card representing a system component, pipeline step, or data entity.
**IMPORTANT: Never use `.node` as a CSS class name.** Mermaid.js internally uses `.node` on its SVG `<g>` elements with `transform: translate(x, y)` for positioning. Any page-level `.node` styles (hover transforms, box-shadows, transitions) will leak into Mermaid diagrams and break their layout. Use `.ve-card` instead (namespaced to avoid collisions with CSS frameworks like Bootstrap/Tailwind that also use `.card`).
```css
.ve-card {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 10px;
padding: 16px 20px;
position: relative;
}
/* Colored accent border (left or top) */
.ve-card--accent-a {
border-left: 3px solid var(--node-a);
}
/* --- Depth tiers: vary card depth to signal importance --- */
/* Elevated: KPIs, key sections, anything that should pop */
.ve-card--elevated {
background: var(--surface-elevated);
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08), 0 1px 2px rgba(0, 0, 0, 0.04);
}
/* Recessed: code blocks, secondary content, detail panels */
.ve-card--recessed {
background: color-mix(in srgb, var(--bg) 70%, var(--surface) 30%);
box-shadow: inset 0 1px 3px rgba(0, 0, 0, 0.06);
border-color: var(--border);
}
/* Hero: executive summaries, focal elements — demands attention */
.ve-card--hero {
background: color-mix(in srgb, var(--surface) 92%, var(--accent) 8%);
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.08), 0 1px 3px rgba(0, 0, 0, 0.04);
border-color: color-mix(in srgb, var(--border) 50%, var(--accent) 50%);
}
/* Glass: special-occasion overlay effect (use sparingly) */
.ve-card--glass {
background: color-mix(in srgb, var(--surface) 60%, transparent 40%);
backdrop-filter: blur(12px);
-webkit-backdrop-filter: blur(12px);
border-color: rgba(255, 255, 255, 0.1);
}
/* Section label (monospace, uppercase, small) */
.ve-card__label {
font-family: var(--font-mono);
font-size: 10px;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 1.5px;
color: var(--node-a);
margin-bottom: 10px;
display: flex;
align-items: center;
gap: 8px;
}
/* Colored dot indicator */
.ve-card__label::before {
content: '';
width: 8px;
height: 8px;
border-radius: 50%;
background: currentColor;
}
```
## Code Blocks
Code blocks need explicit whitespace preservation and a max-height constraint. Without these, code runs together and long files overwhelm the page.
### Basic Pattern
```css
.code-block {
font-family: var(--font-mono);
font-size: 13px;
line-height: 1.5;
background: var(--surface);
border: 1px solid var(--border);
border-radius: 8px;
padding: 16px;
overflow-x: auto;
/* CRITICAL: preserve line breaks and indentation */
white-space: pre-wrap;
word-break: break-word;
}
/* Constrain height for long code */
.code-block--scroll {
max-height: 400px;
overflow-y: auto;
}
```
```html
<pre class="code-block code-block--scroll"><code>// Your code here
function example() {
return true;
}</code></pre>
```
### With File Header
```css
.code-file {
border: 1px solid var(--border);
border-radius: 8px;
overflow: hidden;
}
.code-file__header {
display: flex;
align-items: center;
gap: 8px;
padding: 10px 16px;
background: var(--surface);
border-bottom: 1px solid var(--border);
font-family: var(--font-mono);
font-size: 12px;
color: var(--text-dim);
}
.code-file__body {
font-family: var(--font-mono);
font-size: 13px;
line-height: 1.5;
padding: 16px;
background: var(--surface-elevated);
white-space: pre-wrap;
word-break: break-word;
max-height: 500px;
overflow: auto;
}
```
```html
<div class="code-file">
<div class="code-file__header">
<span>src/extension.ts</span>
</div>
<pre class="code-file__body"><code>export function activate() {
// ...
}</code></pre>
</div>
```
### Implementation Plans: Don't Dump Full Files
For implementation plans and architecture docs, **don't display entire source files inline**. Instead:
1. **Show structure, not code:**
```html
<div class="file-structure">
<div class="file-structure__path">src/extension.ts</div>
<ul class="file-structure__outline">
<li><code>BOOMERANG_INSTRUCTIONS</code> — System prompt for autonomous mode</li>
<li><code>clearState()</code> — Reset extension state</li>
<li><code>updateStatus()</code> — Update UI status indicator</li>
<li><code>/boomerang</code> command — Start autonomous task</li>
<li><code>/boomerang-cancel</code> command — Cancel active task</li>
<li><code>before_agent_start</code> hook — Inject instructions</li>
<li><code>agent_end</code> hook — Generate summary</li>
</ul>
</div>
```
2. **Use collapsible sections for full code:**
```html
<details class="collapsible">
<summary>Full implementation (87 lines)</summary>
<pre class="code-file__body"><code>...</code></pre>
</details>
```
3. **Show key snippets only:**
```html
<p>The core logic intercepts task completion:</p>
<pre class="code-block"><code>pi.on("agent_end", async () => {
const summary = generateSummary(workEntries);
boomerangComplete = true;
});</code></pre>
```
**Anti-patterns:**
- Displaying full source files inline (100+ lines overwhelming the page)
- Code blocks without `white-space: pre-wrap` (code runs together into unreadable wall)
- No height constraint on long code (page becomes endless scroll)
If someone needs the full file, put it in a collapsible section or link to it.
## Directory Tree
For file structures, use `<pre>` with monospace + `white-space: pre`. Tree connectors (`├──`, `└──`, `│`) only work when vertically aligned — they become noise if text wraps.
```css
.dir-tree {
font-family: var(--font-mono);
font-size: 13px;
line-height: 1.7;
background: var(--surface);
border: 1px solid var(--border);
border-radius: 8px;
padding: 16px 20px;
overflow-x: auto;
white-space: pre;
}
.dir-tree .ann { color: var(--text-dim); font-size: 11px; font-style: italic; }
.dir-tree .hl { color: var(--accent); font-weight: 600; }
```
```html
<pre class="dir-tree">my-project/
├── src/
│ ├── <span class="hl">index.ts</span> <span class="ann">— entry point</span>
│ ├── services/
│ │ └── <span class="hl">api.py</span> <span class="ann">(142 lines)</span>
│ └── utils/
├── tests/ <span class="ann">(14 test files)</span>
└── README.md</pre>
```
For labeled trees, wrap in a card. For side-by-side comparisons, put two cards in a grid:
```css
.dir-tree-card { border: 1px solid var(--border); border-radius: 10px; overflow: hidden; }
.dir-tree-card__header {
display: flex; align-items: center; gap: 8px;
padding: 10px 16px; background: var(--surface); border-bottom: 1px solid var(--border);
font-family: var(--font-mono); font-size: 11px; font-weight: 600;
text-transform: uppercase; letter-spacing: 1.5px;
}
.dir-tree-card .dir-tree { border: none; border-radius: 0; }
/* Side-by-side: two .dir-tree-card in a grid */
.dir-compare { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; align-items: start; }
@media (max-width: 900px) { .dir-compare { grid-template-columns: 1fr; } }
```
**Never** render tree connectors inside wrapping text (`white-space: normal`), flex children, or grid items — the vertical pipes lose alignment and the hierarchy becomes unreadable.
## Overflow Protection
Grid and flex children default to `min-width: auto`, which prevents them from shrinking below their content width. Long text, inline code badges, and non-wrapping elements will blow out containers.
### Global rules
```css
/* Every grid/flex child must be able to shrink */
.grid > *, .flex > *,
[style*="display: grid"] > *,
[style*="display: flex"] > * {
min-width: 0;
}
/* Long text wraps instead of overflowing */
body {
overflow-wrap: break-word;
}
```
### Side-by-side comparison panels
```css
.comparison {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 16px;
}
.comparison > * {
min-width: 0;
overflow-wrap: break-word;
}
@media (max-width: 768px) {
.comparison { grid-template-columns: 1fr; }
}
```
### Never use `display: flex` on `<li>` for marker characters
Using `display: flex` on a list item to position a `::before` marker creates an anonymous flex item for the remaining text content. That anonymous flex item gets `min-width: auto` and you **cannot** set `min-width: 0` on anonymous boxes. Lines with many inline `<code>` badges will overflow their container with no CSS fix possible.
Use absolute positioning for markers instead:
```css
/* WRONG — causes overflow with inline code badges */
li {
display: flex;
align-items: baseline;
gap: 6px;
}
li::before {
content: '›';
flex-shrink: 0;
}
/* RIGHT — text wraps normally */
li {
padding-left: 14px;
position: relative;
}
li::before {
content: '›';
position: absolute;
left: 0;
}
```
### List markers overlapping container borders
By default, `list-style-position: outside` places list markers (bullets, numbers) outside the content box. When lists are inside bordered containers (cards, callout boxes), the markers can overlap or extend beyond the border.
```css
/* WRONG — markers overlap container border */
.card ol, .card ul {
padding-left: 20px; /* Not enough for outside markers */
}
/* RIGHT — use inside positioning */
.card ol, .card ul {
list-style-position: inside;
}
/* OR — adequate padding for outside markers */
.card ol, .card ul {
padding-left: 2em; /* ~32px gives room for markers */
}
/* OR — custom markers with absolute positioning (most control) */
.card ol {
list-style: none;
padding-left: 0;
counter-reset: item;
}
.card ol li {
counter-increment: item;
padding-left: 2em;
position: relative;
}
.card ol li::before {
content: counter(item) ".";
position: absolute;
left: 0;
color: var(--accent);
font-weight: 600;
}
```
**Rule of thumb:** Any `<ol>` or `<ul>` inside a bordered container needs either `list-style-position: inside` or `padding-left: 2em` minimum. The default 20px padding is not enough for outside-positioned markers.
## Mermaid Containers
Mermaid diagrams have two common layout issues: they render too small to read, and they left-align in their container leaving awkward dead space (especially for narrow vertical flowcharts).
### Centering (Required)
Mermaid SVGs render at a fixed size based on content. Without explicit centering, they default to top-left alignment. **Always center Mermaid diagrams** — narrow vertical flowcharts look particularly bad when left-aligned in a wide container.
```css
/* WRONG — diagram hugs left edge */
.mermaid-container {
padding: 24px;
border: 1px solid var(--border);
}
/* RIGHT — diagram centers in container */
.mermaid-wrap {
display: flex;
justify-content: center;
align-items: flex-start; /* or center for shorter diagrams */
padding: 24px;
border: 1px solid var(--border);
}
```
### Scaling Small Diagrams
Mermaid sizes diagrams based on content, not container. Complex diagrams with many nodes render small to fit everything, leaving the text nearly unreadable. Three fixes:
**1. Increase fontSize in themeVariables** (most effective):
```javascript
mermaid.initialize({
theme: 'base',
themeVariables: {
fontSize: '18px', // default is 16px, bump to 18-20px for complex diagrams
}
});
```
**2. CSS zoom** for diagrams that still render too small:
```css
.mermaid-wrap--scaled .mermaid {
zoom: 1.3;
}
```
**3. Constrain container width** so the diagram doesn't float in dead space:
```css
.mermaid-wrap--constrained {
max-width: 800px;
margin: 0 auto;
}
```
**Rule of thumb:** If the diagram has 10+ nodes or the text is smaller than 12px rendered, increase fontSize to 18-20px or apply CSS zoom.
### Zoom Controls
Add zoom controls to every `.mermaid-wrap` container for complex diagrams.
**Small diagrams in slides.** If a diagram has fewer than ~7 nodes with no branching, it will render tiny in a full-viewport slide container. For simple linear flows (A → B → C → D), use CSS pipeline cards instead of Mermaid — see `slide-patterns.md` "CSS Pipeline Slide." Reserve Mermaid for complex graphs where automatic edge routing is actually needed.
### Full Pattern
```css
.mermaid-wrap {
position: relative;
background: var(--surface);
border: 1px solid var(--border);
border-radius: 12px;
padding: 32px 24px;
overflow: auto;
/* CRITICAL: center the diagram both horizontally and vertically */
display: flex;
justify-content: center;
align-items: center;
/* Prevent vertical flowcharts from compressing into unreadable thumbnails */
min-height: 400px;
scrollbar-width: thin;
scrollbar-color: var(--border) transparent;
}
.mermaid-wrap::-webkit-scrollbar { width: 6px; height: 6px; }
.mermaid-wrap::-webkit-scrollbar-track { background: transparent; }
.mermaid-wrap::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
.mermaid-wrap::-webkit-scrollbar-thumb:hover { background: var(--text-dim); }
/* For shorter diagrams that don't need the full height */
.mermaid-wrap--compact { min-height: 200px; }
/* For very tall vertical flowcharts */
.mermaid-wrap--tall { min-height: 600px; }
.mermaid-wrap .mermaid {
/* Use CSS zoom instead of transform: scale().
Zoom changes actual layout size, so overflow scrolls normally in all directions.
Transform only changes visual appearance — content expanding upward/leftward
goes into negative space which can't be scrolled to.
Supported in all browsers (Firefox added support in v126, June 2024).
Note: zoom is not animatable, so no transition. */
/* Optional: start at >1 for complex diagrams that render too small.
The diagram stays centered, renders larger, and zoom controls still work. */
zoom: 1.4;
}
.zoom-controls {
position: absolute;
top: 8px;
right: 8px;
display: flex;
gap: 2px;
z-index: 10;
background: var(--surface);
border: 1px solid var(--border);
border-radius: 6px;
padding: 2px;
}
.zoom-controls button {
width: 28px;
height: 28px;
border: none;
background: transparent;
color: var(--text-dim);
font-family: var(--font-mono);
font-size: 14px;
cursor: pointer;
border-radius: 4px;
display: flex;
align-items: center;
justify-content: center;
transition: background 0.15s ease, color 0.15s ease;
}
.zoom-controls button:hover {
background: var(--border);
color: var(--text);
}
.mermaid-wrap { cursor: grab; }
.mermaid-wrap.is-panning { cursor: grabbing; user-select: none; }
```
**Why zoom instead of transform?**
CSS `transform: scale()` only changes visual appearance — the element's layout box stays the same size. When you scale from `center center`, content expands upward and leftward into negative coordinate space. Scroll containers can't scroll to negative positions, so the top and left of the zoomed content get clipped.
CSS `zoom` actually changes the element's layout size. The content grows downward and rightward like any other growing element, staying fully scrollable.
### HTML
```html
<div class="mermaid-wrap">
<div class="zoom-controls">
<button onclick="zoomDiagram(this, 1.2)" title="Zoom in">+</button>
<button onclick="zoomDiagram(this, 0.8)" title="Zoom out">−</button>
<button onclick="resetZoom(this)" title="Reset zoom">↺</button>
<button onclick="openDiagramFullscreen(this)" title="Open full size in new tab">⛶</button>
</div>
<pre class="mermaid">
graph TD
A --> B
</pre>
</div>
```
**Click to expand.** Clicking anywhere on the diagram (without dragging) opens it full-size in a new tab. The expand button (⛶) in the zoom controls does the same thing.
### JavaScript
Add once at the end of the page. Handles button clicks and scroll-to-zoom on all `.mermaid-wrap` containers:
```javascript
// Match this to the CSS zoom value (or 1 if not set)
var INITIAL_ZOOM = 1.4;
function zoomDiagram(btn, factor) {
var wrap = btn.closest('.mermaid-wrap');
var target = wrap.querySelector('.mermaid');
var current = parseFloat(target.dataset.zoom || INITIAL_ZOOM);
var next = Math.min(Math.max(current * factor, 0.5), 5);
target.dataset.zoom = next;
target.style.zoom = next;
}
function resetZoom(btn) {
var wrap = btn.closest('.mermaid-wrap');
var target = wrap.querySelector('.mermaid');
target.dataset.zoom = INITIAL_ZOOM;
target.style.zoom = INITIAL_ZOOM;
}
function openDiagramFullscreen(btn) {
var wrap = btn.closest('.mermaid-wrap');
openMermaidInNewTab(wrap);
}
function openMermaidInNewTab(wrap) {
var svg = wrap.querySelector('.mermaid svg');
if (!svg) return;
// Clone the SVG and remove any inline transforms from zoom
var clone = svg.cloneNode(true);
clone.style.zoom = '';
clone.style.transform = '';
// Get computed styles for theming
var styles = getComputedStyle(document.documentElement);
var bg = styles.getPropertyValue('--bg').trim() || '#ffffff';
// Build standalone HTML page
var html = '<!DOCTYPE html>' +
'<html lang="en"><head><meta charset="UTF-8">' +
'<meta name="viewport" content="width=device-width, initial-scale=1.0">' +
'<title>Diagram</title>' +
'<style>' +
'body { margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center; background: ' + bg + '; padding: 40px; box-sizing: border-box; }' +
'svg { max-width: 100%; max-height: 90vh; height: auto; }' +
'</style></head><body>' +
clone.outerHTML +
'</body></html>';
var blob = new Blob([html], { type: 'text/html' });
var url = URL.createObjectURL(blob);
window.open(url, '_blank');
}
document.querySelectorAll('.mermaid-wrap').forEach(function(wrap) {
// Ctrl/Cmd + scroll to zoom
wrap.addEventListener('wheel', function(e) {
if (!e.ctrlKey && !e.metaKey) return;
e.preventDefault();
var target = wrap.querySelector('.mermaid');
var current = parseFloat(target.dataset.zoom || INITIAL_ZOOM);
var factor = e.deltaY < 0 ? 1.1 : 0.9;
var next = Math.min(Math.max(current * factor, 0.5), 5);
target.dataset.zoom = next;
target.style.zoom = next;
}, { passive: false });
// Click-and-drag to pan, click (without drag) to open full-size
var startX, startY, scrollL, scrollT, startTime, didPan;
wrap.addEventListener('mousedown', function(e) {
if (e.target.closest('.zoom-controls')) return;
wrap.classList.add('is-panning');
startX = e.clientX;
startY = e.clientY;
scrollL = wrap.scrollLeft;
scrollT = wrap.scrollTop;
startTime = Date.now();
didPan = false;
});
window.addEventListener('mousemove', function(e) {
if (!wrap.classList.contains('is-panning')) return;
var dx = e.clientX - startX;
var dy = e.clientY - startY;
if (Math.abs(dx) > 5 || Math.abs(dy) > 5) didPan = true;
wrap.scrollLeft = scrollL - dx;
wrap.scrollTop = scrollT - dy;
});
window.addEventListener('mouseup', function() {
if (!wrap.classList.contains('is-panning')) return;
wrap.classList.remove('is-panning');
// If click was quick and didn't move much, open full-size
var elapsed = Date.now() - startTime;
if (!didPan && elapsed < 300) {
openMermaidInNewTab(wrap);
}
});
});
```
Scroll-to-zoom requires Ctrl/Cmd+scroll to avoid hijacking normal page scroll. Cursor changes to `grab`/`grabbing` to signal pan mode. The zoom range is capped at 0.5x–5x. **Clicking without dragging opens the diagram full-size in a new browser tab.**
## Grid Layouts
### Architecture Diagram (2-column with sidebar)
```css
.arch-grid {
display: grid;
grid-template-columns: 260px 1fr;
grid-template-rows: auto;
gap: 20px;
max-width: 1100px;
margin: 0 auto;
}
.arch-grid__sidebar { grid-column: 1; }
.arch-grid__main { grid-column: 2; }
.arch-grid__full { grid-column: 1 / -1; }
```
### Pipeline (horizontal steps)
```css
.pipeline {
display: flex;
align-items: stretch;
gap: 0;
overflow-x: auto;
padding-bottom: 8px;
}
.pipeline__step {
min-width: 130px;
flex-shrink: 0;
}
.pipeline__arrow {
display: flex;
align-items: center;
padding: 0 4px;
color: var(--border-bright);
font-size: 18px;
flex-shrink: 0;
}
/* Parallel branch within a pipeline */
.pipeline__parallel {
display: flex;
flex-direction: column;
gap: 6px;
}
```
### Card Grid (dashboard / metrics)
```css
.card-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
gap: 16px;
}
```
### Data Tables
Use real `<table>` elements for tabular data. Wrap in a scrollable container for wide tables.
```css
/* Scrollable wrapper for wide tables */
.table-wrap {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 12px;
overflow: hidden;
}
.table-scroll {
overflow-x: auto;
-webkit-overflow-scrolling: touch;
}
/* Base table */
.data-table {
width: 100%;
border-collapse: collapse;
font-size: 13px;
line-height: 1.5;
}
/* Header */
.data-table thead {
position: sticky;
top: 0;
z-index: 2;
}
.data-table th {
background: var(--surface-elevated, var(--surface2, var(--surface)));
font-family: var(--font-mono);
font-size: 11px;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 1px;
color: var(--text-dim);
text-align: left;
padding: 12px 16px;
border-bottom: 2px solid var(--border-bright);
white-space: nowrap;
}
/* Cells */
.data-table td {
padding: 12px 16px;
border-bottom: 1px solid var(--border);
vertical-align: top;
color: var(--text);
}
/* Let text-heavy columns wrap naturally */
.data-table .wide {
min-width: 200px;
max-width: 500px;
}
/* Right-align numeric columns */
.data-table td.num,
.data-table th.num {
text-align: right;
font-variant-numeric: tabular-nums;
font-family: var(--font-mono);
}
/* Alternating rows */
.data-table tbody tr:nth-child(even) {
background: var(--accent-dim);
}
/* Row hover */
.data-table tbody tr {
transition: background 0.15s ease;
}
.data-table tbody tr:hover {
background: var(--border);
}
/* Last row: no bottom border (container handles it) */
.data-table tbody tr:last-child td {
border-bottom: none;
}
/* Code inside cells */
.data-table code {
font-family: var(--font-mono);
font-size: 11px;
background: var(--accent-dim);
color: var(--accent);
padding: 1px 5px;
border-radius: 3px;
}
/* Secondary detail text */
.data-table small {
display: block;
color: var(--text-dim);
font-size: 11px;
margin-top: 2px;
}
```
#### Status Indicators
Styled spans for match/gap/warning states. Never use emoji.
```css
.status {
display: inline-flex;
align-items: center;
gap: 6px;
font-family: var(--font-mono);
font-size: 11px;
font-weight: 500;
padding: 3px 10px;
border-radius: 6px;
white-space: nowrap;
}
.status--match {
background: var(--green-dim, rgba(5, 150, 105, 0.1));
color: var(--green, #059669);
}
.status--gap {
background: var(--red-dim, rgba(239, 68, 68, 0.1));
color: var(--red, #ef4444);
}
.status--warn {
background: var(--orange-dim, rgba(217, 119, 6, 0.1));
color: var(--orange, #d97706);
}
.status--info {
background: var(--accent-dim);
color: var(--accent);
}
/* Dot variant (compact, no text) */
.status-dot {
width: 8px;
height: 8px;
border-radius: 50%;
display: inline-block;
}
.status-dot--match { background: var(--green, #059669); }
.status-dot--gap { background: var(--red, #ef4444); }
.status-dot--warn { background: var(--orange, #d97706); }
```
Usage in table cells:
```html
<td><span class="status status--match">Match</span></td>
<td><span class="status status--gap">Gap</span></td>
<td><span class="status status--warn">Partial</span></td>
```
#### Table Summary Row
For totals, counts, or aggregate status at the bottom:
```css
.data-table tfoot td {
background: var(--surface-elevated, var(--surface2, var(--surface)));
font-weight: 600;
font-size: 12px;
border-top: 2px solid var(--border-bright);
border-bottom: none;
padding: 12px 16px;
}
```
#### Sticky First Column (for very wide tables)
```css
.data-table th:first-child,
.data-table td:first-child {
position: sticky;
left: 0;
z-index: 1;
background: var(--surface);
}
.data-table tbody tr:nth-child(even) td:first-child {
background: color-mix(in srgb, var(--surface) 95%, var(--accent) 5%);
}
```
## Connectors
### CSS Arrow (vertical, between stacked sections)
```css
.flow-arrow {
display: flex;
justify-content: center;
align-items: center;
gap: 8px;
color: var(--text-dim);
font-family: var(--font-mono);
font-size: 12px;
padding: 6px 0;
}
/* Down arrow via SVG icon */
.flow-arrow svg {
width: 20px;
height: 20px;
fill: none;
stroke: var(--border-bright);
stroke-width: 2;
stroke-linecap: round;
stroke-linejoin: round;
}
```
Down arrow SVG (reuse inline):
```html
<svg viewBox="0 0 20 20"><path d="M10 4 L10 16 M6 12 L10 16 L14 12"/></svg>
```
### CSS Arrow (horizontal, between inline steps)
Use `::after` or a literal arrow character:
```css
.h-arrow::after {
content: '→';
color: var(--border-bright);
font-size: 18px;
padding: 0 4px;
}
```
### SVG Curved Connector (between arbitrary nodes)
For connections that aren't simple vertical/horizontal, use an absolutely positioned SVG overlay:
```html
<svg class="connectors" style="position:absolute;inset:0;width:100%;height:100%;pointer-events:none;">
<path d="M 150,100 C 150,200 350,100 350,200" fill="none" stroke="var(--accent)" stroke-width="1.5" stroke-dasharray="4 3"/>
<!-- Arrowhead -->
<polygon points="348,195 352,205 356,195" fill="var(--accent)"/>
</svg>
```
Position the parent container as `position: relative` to scope the SVG overlay.
## Animations
### Staggered Fade-In on Load
Define the keyframe once, then stagger via a `--i` CSS variable set per element. This approach works regardless of DOM nesting or interleaved non-animated elements (unlike `nth-child` which breaks when siblings aren't all the same type).
```css
@keyframes fadeUp {
from { opacity: 0; transform: translateY(12px); }
to { opacity: 1; transform: translateY(0); }
}
.ve-card {
animation: fadeUp 0.4s ease-out both;
animation-delay: calc(var(--i, 0) * 0.05s);
}
```
Set `--i` per element in the HTML to control stagger order:
```html
<div class="ve-card" style="--i: 0">First</div>
<div class="connector">...</div>
<div class="ve-card" style="--i: 1">Second</div>
<div class="connector">...</div>
<div class="ve-card" style="--i: 2">Third</div>
```
### Hover Lift
```css
.ve-card {
transition: transform 0.2s ease, box-shadow 0.2s ease;
}
.ve-card:hover {
transform: translateY(-2px);
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}
```
### Scale-Fade (for KPI cards, badges, status indicators)
```css
@keyframes fadeScale {
from { opacity: 0; transform: scale(0.92); }
to { opacity: 1; transform: scale(1); }
}
.kpi-card {
animation: fadeScale 0.35s ease-out both;
animation-delay: calc(var(--i, 0) * 0.06s);
}
```
### SVG Draw-In (for connectors, progress rings, path elements)
```css
@keyframes drawIn {
from { stroke-dashoffset: var(--path-length); }
to { stroke-dashoffset: 0; }
}
/* Set --path-length to the path's getTotalLength() value */
.connector path {
stroke-dasharray: var(--path-length);
animation: drawIn 0.8s ease-in-out both;
animation-delay: calc(var(--i, 0) * 0.1s);
}
```
### CSS Counter (for hero numbers without JS)
Uses `@property` to animate a custom property as an integer, then display it via `counter()`. No JS required. Falls back to showing the final value immediately in browsers without `@property` support.
```css
@property --count {
syntax: '<integer>';
initial-value: 0;
inherits: false;
}
@keyframes countUp {
to { --count: var(--target); }
}
.kpi-card__value--animated {
--target: 247;
counter-reset: val var(--count);
animation: countUp 1.2s ease-out forwards;
}
.kpi-card__value--animated::after {
content: counter(val);
}
```
### Choreography
Don't use the same animation for everything. Mix types by element role, with easing stagger (fast-then-slow, not linear):
- **Cards**: `fadeUp` — the default entrance, reliable and subtle
- **KPI / badges**: `fadeScale` — scale draws the eye to important numbers
- **SVG connectors**: `drawIn` — reveals flow direction, pairs with card stagger
- **Hero numbers**: `countUp` — counting motion signals "this number matters"
- **Stagger timing**: `calc(var(--i) * 0.06s)` with lower `--i` values on important elements so they appear first
### Respect Reduced Motion
```css
@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
}
}
```
## Sparklines and Simple Charts (Pure SVG)
For simple inline visualizations without a library:
```html
<!-- Sparkline -->
<svg viewBox="0 0 100 30" style="width:100px;height:30px;">
<polyline points="0,25 15,20 30,22 45,10 60,15 75,5 90,12 100,8"
fill="none" stroke="var(--accent)" stroke-width="1.5" stroke-linecap="round"/>
</svg>
<!-- Progress bar -->
<div style="height:6px;background:var(--border);border-radius:3px;overflow:hidden;">
<div style="height:100%;width:72%;background:var(--accent);border-radius:3px;"></div>
</div>
```
## Responsive Breakpoint
Include a single breakpoint for narrow viewports:
```css
@media (max-width: 768px) {
.arch-grid { grid-template-columns: 1fr; }
.pipeline { flex-wrap: wrap; gap: 8px; }
.pipeline__arrow { display: none; }
body { padding: 16px; }
}
```
## Badges and Tags
Small inline labels for categorizing elements:
```css
.tag {
font-family: var(--font-mono);
font-size: 10px;
font-weight: 500;
padding: 2px 7px;
border-radius: 4px;
background: var(--node-a-dim);
color: var(--node-a);
}
```
## Lists Inside Nodes
For tool listings, feature lists, table columns:
```css
.node-list {
list-style: none;
padding: 0;
margin: 0;
font-size: 12px;
line-height: 1.8;
}
.node-list li {
padding-left: 14px;
position: relative;
}
.node-list li::before {
content: '›';
color: var(--text-dim);
font-weight: 600;
position: absolute;
left: 0;
}
.node-list code {
font-family: var(--font-mono);
font-size: 11px;
background: var(--accent-dim);
color: var(--accent);
padding: 1px 5px;
border-radius: 3px;
}
```
## KPI / Metric Cards
Large hero number with trend indicator and label. For dashboards, review summaries, and impact sections.
```css
.kpi-row {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
gap: 16px;
}
.kpi-card {
background: var(--surface-elevated);
border: 1px solid var(--border);
border-radius: 10px;
padding: 20px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);
}
.kpi-card__value {
font-size: 36px;
font-weight: 700;
letter-spacing: -1px;
line-height: 1.1;
font-variant-numeric: tabular-nums;
}
.kpi-card__label {
font-family: var(--font-mono);
font-size: 10px;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 1.5px;
color: var(--text-dim);
margin-top: 6px;
}
.kpi-card__trend {
font-family: var(--font-mono);
font-size: 12px;
margin-top: 4px;
}
.kpi-card__trend--up { color: var(--node-b, #059669); }
.kpi-card__trend--down { color: var(--red, #ef4444); }
```
```html
<div class="kpi-row">
<div class="kpi-card">
<div class="kpi-card__value">247</div>
<div class="kpi-card__label">Lines Added</div>
<div class="kpi-card__trend kpi-card__trend--up">+34%</div>
</div>
<!-- ... more cards -->
</div>
```
## Before / After Panels
Two-column comparison with diff-colored headers. For review pages, migration docs, and feature comparisons.
```css
.diff-panels {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 0;
border: 1px solid var(--border);
border-radius: 10px;
overflow: hidden;
}
.diff-panels > * { min-width: 0; overflow-wrap: break-word; }
.diff-panel__header {
font-family: var(--font-mono);
font-size: 11px;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 1px;
padding: 10px 16px;
}
.diff-panel__header--before {
background: var(--red-dim, rgba(239, 68, 68, 0.08));
color: var(--red, #ef4444);
border-bottom: 2px solid var(--red, #ef4444);
}
.diff-panel__header--after {
background: var(--green-dim, rgba(5, 150, 105, 0.08));
color: var(--green, #059669);
border-bottom: 2px solid var(--green, #059669);
}
.diff-panel__body {
padding: 16px;
background: var(--surface);
font-size: 13px;
line-height: 1.6;
}
/* Highlight changed items within a panel */
.diff-changed {
background: var(--accent-dim);
border-radius: 3px;
padding: 0 3px;
}
@media (max-width: 768px) {
.diff-panels { grid-template-columns: 1fr; }
}
```
```html
<div class="diff-panels">
<div class="diff-panel__header diff-panel__header--before">Before</div>
<div class="diff-panel__header diff-panel__header--after">After</div>
<div class="diff-panel__body">Previous implementation...</div>
<div class="diff-panel__body">New implementation...</div>
</div>
```
## Collapsible Sections
Native `<details>/<summary>` with styled disclosure. Zero JS, accessible. For lower-priority content: file maps, decision logs, reference sections.
```css
details.collapsible {
border: 1px solid var(--border);
border-radius: 10px;
overflow: hidden;
}
details.collapsible summary {
padding: 14px 20px;
background: var(--surface);
font-family: var(--font-mono);
font-size: 12px;
font-weight: 600;
cursor: pointer;
list-style: none;
display: flex;
align-items: center;
gap: 8px;
color: var(--text);
transition: background 0.15s ease;
}
details.collapsible summary:hover {
background: var(--surface-elevated, var(--surface));
}
details.collapsible summary::-webkit-details-marker { display: none; }
/* Chevron indicator */
details.collapsible summary::before {
content: '▸';
font-size: 11px;
color: var(--text-dim);
transition: transform 0.15s ease;
}
details.collapsible[open] summary::before {
transform: rotate(90deg);
}
details.collapsible .collapsible__body {
padding: 16px 20px;
border-top: 1px solid var(--border);
font-size: 13px;
line-height: 1.6;
}
```
```html
<details class="collapsible">
<summary>File Map (14 files changed)</summary>
<div class="collapsible__body">
<!-- content here -->
</div>
</details>
```
## Prose Page Elements
Patterns for documentation, articles, blog posts, and other reading-first content. The key difference from visual explanations: optimize for sustained reading, not scanning.
### Body Text Settings
```css
/* Comfortable reading baseline */
.prose {
font-size: clamp(17px, 1.1vw + 14px, 19px);
line-height: 1.7;
max-width: 65ch; /* ~600-680px */
text-wrap: pretty;
}
.prose p {
margin-bottom: 1.5em;
}
/* Narrow column for essays/literary content */
.prose--narrow {
max-width: 60ch;
line-height: 1.8;
}
/* Wide column for technical content with code */
.prose--wide {
max-width: 75ch;
line-height: 1.6;
}
```
### Lead Paragraph
Opening paragraph styled distinctly from body text.
```css
/* Larger size */
.lead {
font-size: 20px;
line-height: 1.6;
color: var(--text-bright);
margin-bottom: 32px;
}
/* With drop cap */
.lead--dropcap::first-letter {
float: left;
font-family: var(--font-display);
font-size: 64px;
font-weight: 600;
line-height: 0.85;
padding-right: 12px;
padding-top: 6px;
color: var(--accent);
}
```
### Pull Quotes
Key insights pulled out for emphasis. Use sparingly — one or two per article maximum.
```css
/* Border left — most versatile */
.pullquote {
margin: 48px 0;
padding-left: 24px;
border-left: 3px solid var(--accent);
}
.pullquote p {
font-size: 22px;
font-style: italic;
line-height: 1.4;
color: var(--text-bright);
margin: 0;
}
/* Centered with quotation mark */
.pullquote--centered {
margin: 56px 0;
padding: 32px 40px;
border-top: 1px solid var(--border);
border-bottom: 1px solid var(--border);
text-align: center;
position: relative;
}
.pullquote--centered::before {
content: '"';
position: absolute;
top: -12px;
left: 50%;
transform: translateX(-50%);
background: var(--bg);
padding: 0 16px;
font-family: var(--font-display);
font-size: 48px;
color: var(--accent);
line-height: 1;
}
```
### Section Dividers
```css
/* Horizontal rule */
hr {
border: none;
height: 1px;
background: var(--border);
margin: 48px 0;
}
/* Ornamental divider — use: <div class="divider">✦ ✦ ✦</div> */
.divider {
text-align: center;
margin: 48px 0;
color: var(--text-dim);
font-size: 18px;
letter-spacing: 12px;
}
```
### Article Hero Patterns
```css
/* Centered minimal — essays, personal posts */
.hero--centered {
text-align: center;
padding: 80px 24px 64px;
max-width: 800px;
margin: 0 auto;
}
.hero__category {
font-size: 12px;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 2px;
color: var(--accent);
margin-bottom: 16px;
}
.hero__title {
font-size: clamp(32px, 5vw, 48px);
font-weight: 600;
line-height: 1.15;
margin-bottom: 16px;
}
.hero__subtitle {
font-size: 20px;
font-style: italic;
color: var(--text-dim);
max-width: 600px;
margin: 0 auto 24px;
}
.hero__meta {
font-size: 13px;
color: var(--text-dim);
}
/* Left-aligned editorial — features, documentation */
.hero--editorial {
padding: 100px 40px 60px;
max-width: 1000px;
margin: 0 auto;
}
.hero--editorial .hero__title {
font-size: clamp(40px, 7vw, 72px);
font-weight: 800;
line-height: 1.0;
letter-spacing: -2px;
}
```
### Author Byline
```css
.byline {
display: flex;
align-items: center;
gap: 12px;
margin-top: 24px;
}
.byline__avatar {
width: 40px;
height: 40px;
border-radius: 50%;
}
.byline__name {
font-weight: 600;
color: var(--text-bright);
display: block;
}
.byline__meta {
font-size: 13px;
color: var(--text-dim);
}
```
### Callout Boxes
For warnings, tips, notes, and key takeaways.
```css
.callout {
padding: 16px 20px;
border-radius: 8px;
border-left: 4px solid var(--callout-border);
background: var(--callout-bg);
margin: 24px 0;
}
.callout--info {
--callout-border: var(--accent);
--callout-bg: color-mix(in srgb, var(--accent) 10%, transparent);
}
.callout--warning {
--callout-border: var(--amber);
--callout-bg: color-mix(in srgb, var(--amber) 10%, transparent);
}
.callout--success {
--callout-border: var(--green);
--callout-bg: color-mix(in srgb, var(--green) 10%, transparent);
}
.callout__title {
font-weight: 600;
margin-bottom: 8px;
color: var(--callout-border);
}
/* Lists inside callouts need padding fix */
.callout ul, .callout ol {
padding-left: 1.5em;
margin: 8px 0 0 0;
}
```
### Theme Toggle
Use `data-theme` attribute for user-controllable light/dark modes. Random initial theme adds variety.
```css
:root, [data-theme="light"] {
--bg: #fafaf9;
--surface: #ffffff;
--text: #1c1917;
--text-dim: #78716c;
--border: #e7e5e4;
--accent: #0d9488;
}
[data-theme="dark"] {
--bg: #0c0a09;
--surface: #1c1917;
--text: #fafaf9;
--text-dim: #a8a29e;
--border: #292524;
--accent: #14b8a6;
}
```
```javascript
// Random initial theme
const themes = ['light', 'dark'];
document.documentElement.setAttribute('data-theme', themes[Math.floor(Math.random() * 2)]);
// Toggle function
function toggleTheme() {
const current = document.documentElement.getAttribute('data-theme');
document.documentElement.setAttribute('data-theme', current === 'light' ? 'dark' : 'light');
}
```
```html
<button class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle theme">
<svg class="theme-toggle__sun" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
<circle cx="12" cy="12" r="5"/><path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/>
</svg>
<svg class="theme-toggle__moon" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
<path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
</svg>
</button>
```
```css
.theme-toggle {
position: fixed;
top: 20px;
right: 20px;
background: var(--surface);
border: 1px solid var(--border);
border-radius: 8px;
padding: 8px;
cursor: pointer;
z-index: 100;
}
[data-theme="light"] .theme-toggle__moon { display: none; }
[data-theme="dark"] .theme-toggle__sun { display: none; }
```
### Prose Anti-Patterns
Avoid these in reading-first content:
- Body text smaller than 16px
- Line-height below 1.5
- Measure wider than 75ch (text spanning full viewport)
- Pull quotes every other paragraph
- Drop caps on every section
- Busy background patterns behind text
## Generated Images
For AI-generated illustrations embedded as base64 data URIs via `surf gemini --generate-image`. Use sparingly — hero banners, conceptual illustrations, educational diagrams, decorative accents.
### Hero Banner
Full-width image cropped to a fixed height with a gradient fade into the page background. Place at the top of the page before the title, or between the title and the first content section.
```css
.hero-img-wrap {
position: relative;
border-radius: 12px;
overflow: hidden;
margin-bottom: 24px;
}
.hero-img-wrap img {
width: 100%;
height: 240px;
object-fit: cover;
display: block;
}
/* Gradient fade into page background */
.hero-img-wrap::after {
content: '';
position: absolute;
bottom: 0;
left: 0;
right: 0;
height: 50%;
background: linear-gradient(to top, var(--bg), transparent);
pointer-events: none;
}
```
```html
<div class="hero-img-wrap">
<img src="data:image/png;base64,..." alt="Descriptive alt text">
</div>
```
Generate with `--aspect-ratio 16:9` for hero banners.
### Inline Illustration
Centered image with border, shadow, and optional caption. Use within content sections for conceptual or educational illustrations.
```css
.illus {
text-align: center;
margin: 24px 0;
}
.illus img {
max-width: 480px;
width: 100%;
border-radius: 10px;
border: 1px solid var(--border);
box-shadow: 0 2px 12px rgba(0, 0, 0, 0.08);
}
.illus figcaption {
font-family: var(--font-mono);
font-size: 11px;
color: var(--text-dim);
margin-top: 8px;
}
```
```html
<figure class="illus">
<img src="data:image/png;base64,..." alt="Descriptive alt text">
<figcaption>How the message queue routes events between services</figcaption>
</figure>
```
Generate with `--aspect-ratio 1:1` or `--aspect-ratio 4:3` for inline illustrations.
### Side Accent
Small image floated beside a section. Use when the illustration supports but doesn't dominate the content.
```css
.accent-img {
float: right;
max-width: 200px;
margin: 0 0 16px 24px;
border-radius: 10px;
border: 1px solid var(--border);
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);
}
@media (max-width: 768px) {
.accent-img {
float: none;
max-width: 100%;
margin: 0 0 16px 0;
}
}
```
```html
<img class="accent-img" src="data:image/png;base64,..." alt="Descriptive alt text">
```
# External Libraries (CDN)
Optional CDN libraries for cases where pure CSS/HTML isn't enough. Only include what the diagram actually needs — most diagrams need zero external JS.
## Mermaid.js — Diagramming Engine
Use for flowcharts, sequence diagrams, ER diagrams, state machines, mind maps, class diagrams, and any diagram where automatic node positioning and edge routing saves effort. Mermaid handles layout — you handle theming.
Do NOT use for dashboards — CSS Grid card layouts with Chart.js look better for those. Data tables use `<table>` elements.
**CDN:**
```html
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true, /* ... */ });
</script>
```
**With ELK layout** (required for `layout: 'elk'` — it's a separate package, not bundled in core):
```html
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
import elkLayouts from 'https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk/dist/mermaid-layout-elk.esm.min.mjs';
mermaid.registerLayoutLoaders(elkLayouts);
mermaid.initialize({ startOnLoad: true, layout: 'elk', /* ... */ });
</script>
```
Without the ELK import and registration, `layout: 'elk'` silently falls back to dagre. Only import ELK when you actually need it — it adds significant bundle weight. Most simple diagrams render fine with dagre.
### Deep Theming
Always use `theme: 'base'` — it's the only theme where all `themeVariables` are fully customizable. The built-in themes (`default`, `dark`, `forest`, `neutral`) ignore most variable overrides.
```html
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
mermaid.initialize({
startOnLoad: true,
theme: 'base',
look: 'classic',
themeVariables: {
// Background and surfaces — teal/slate palette (not violet/indigo!)
primaryColor: isDark ? '#134e4a' : '#ccfbf1',
primaryBorderColor: isDark ? '#14b8a6' : '#0d9488',
primaryTextColor: isDark ? '#f0fdfa' : '#134e4a',
secondaryColor: isDark ? '#1e293b' : '#f0fdf4',
secondaryBorderColor: isDark ? '#059669' : '#16a34a',
secondaryTextColor: isDark ? '#f1f5f9' : '#1e293b',
tertiaryColor: isDark ? '#27201a' : '#fef3c7',
tertiaryBorderColor: isDark ? '#d97706' : '#f59e0b',
tertiaryTextColor: isDark ? '#fef3c7' : '#27201a',
// Lines and edges
lineColor: isDark ? '#64748b' : '#94a3b8',
// Text
fontSize: '16px',
fontFamily: 'var(--font-body)',
// Notes and labels
noteBkgColor: isDark ? '#1e293b' : '#fefce8',
noteTextColor: isDark ? '#f1f5f9' : '#1e293b',
noteBorderColor: isDark ? '#fbbf24' : '#d97706',
}
});
</script>
```
**FORBIDDEN in Mermaid themeVariables:** `#8b5cf6`, `#7c3aed`, `#a78bfa` (indigo/violet), `#d946ef` (fuchsia). Use teal, slate, amber, emerald, or colors from your page's palette.
### CSS Overrides on Mermaid SVG
Mermaid renders SVG. Override its classes for pixel-perfect control that `themeVariables` can't reach:
```css
/* Container — see css-patterns.md "Mermaid Zoom Controls" for the full zoom pattern */
.mermaid-wrap {
position: relative;
background: var(--surface);
border: 1px solid var(--border);
border-radius: 12px;
padding: 24px;
overflow: auto;
}
/* CRITICAL: Force node/edge text to follow the page's color scheme.
Without this, themeVariables.primaryTextColor works for DEFAULT nodes,
but any classDef that sets color: will hardcode a single value that
breaks in the opposite color scheme. Fix: never set color: in classDef,
and always include these CSS overrides. */
.mermaid .nodeLabel { color: var(--text) !important; }
.mermaid .edgeLabel { color: var(--text-dim) !important; background-color: var(--bg) !important; }
.mermaid .edgeLabel rect { fill: var(--bg) !important; }
/* Node shapes */
.mermaid .node rect,
.mermaid .node circle,
.mermaid .node polygon {
stroke-width: 1.5px;
}
/* Edge paths */
.mermaid .edge-pattern-solid {
stroke-width: 1.5px;
}
/* Edge labels — smaller than node labels for visual hierarchy */
.mermaid .edgeLabel {
font-family: var(--font-mono) !important;
font-size: 13px !important;
}
/* Node labels — 16px default; drop to 14px for complex diagrams (20+ nodes) */
.mermaid .nodeLabel {
font-family: var(--font-body) !important;
font-size: 16px !important;
}
/* Sequence diagram actors */
.mermaid .actor {
stroke-width: 1.5px;
}
/* Sequence diagram messages */
.mermaid .messageText {
font-family: var(--font-mono) !important;
font-size: 12px !important;
}
/* ER diagram entities */
.mermaid .er.entityBox {
stroke-width: 1.5px;
}
/* Mind map nodes */
.mermaid .mindmap-node rect {
stroke-width: 1.5px;
}
```
### classDef and style Gotchas
`classDef` values and per-node `style` directives are static text inside `<pre>` — they can't use CSS variables or JS ternaries. Two rules:
1. **Never set `color:` in classDef or per-node `style` directives.** It hardcodes a text color that breaks in the opposite color scheme. This applies to both `classDef highlight fill:...,color:#2c2a25` and `style I fill:...,color:#2c2a25`. Let the CSS overrides above handle text color via `var(--text)`.
2. **Use semi-transparent fills (8-digit hex) for node backgrounds.** They layer over whatever Mermaid's base theme background is, producing a tint that works in both light and dark modes. Use `20`–`44` alpha for subtle, `55`–`77` for prominent:
```
classDef highlight fill:#b5761433,stroke:#b57614,stroke-width:2px
classDef muted fill:#7c6f6411,stroke:#7c6f6444,stroke-width:1px
```
### Node Label Special Characters
Mermaid uses certain characters for shape syntax. Node labels containing these characters cause syntax errors unless quoted.
**Shape characters to watch:**
- `[/text/]` — parallelogram
- `[\text\]` — trapezoid (alt)
- `[/text\]` — trapezoid
- `[\text/]` — trapezoid (alt)
- `[(text)]` — cylindrical
- `[[text]]` — subroutine
- `((text))` — circle
- `{{text}}` — hexagon
**If your node label starts with `/`, `\`, `(`, or `{`, wrap it in quotes:**
```
%% WRONG — syntax error (/ starts parallelogram shape)
CMD[/gallery command] --> SRV[server]
%% RIGHT — quotes escape the special character
CMD["/gallery command"] --> SRV[server]
```
**Edge labels with special characters also need quotes:**
```
%% WRONG — quotes inside edge label
UI -->|"Use as Reference"| RET
%% RIGHT — use single quotes or escape
UI -->|'Use as Reference'| RET
UI -->|Use as Reference| RET
```
Avoid opaque light fills like `fill:#fefce8` — they render as bright boxes in dark mode.
### stateDiagram-v2 Label Limitations
State diagram transition labels have a strict parser. Avoid:
- `<br/>` — only works in flowcharts; causes a parse error in state diagrams
- Parentheses in labels — `cancel()` can confuse the parser
- Multiple colons — the first `:` is the label delimiter; extra colons in the label text may break parsing
If you need multi-line labels or special characters, use a `flowchart` instead of `stateDiagram-v2`. Flowcharts support quoted labels (`|"label with: special chars"|`) and `<br/>` for line breaks.
### Writing Valid Mermaid
Most Mermaid failures come from a few recurring issues. Follow these rules to avoid invalid diagrams:
**For multi-line flowchart node labels, use `<br/>` (not `\n`).** Mermaid flowcharts interpret `<br/>` as a line break, but escaped `\n` in labels often renders as literal text:
```
%% WRONG — renders literal "\n" in node text
A["Copilot Backend\n/api + /api/voicebot"] --> B["Redis"]
%% RIGHT — renders on two lines
A["Copilot Backend<br/>/api + /api/voicebot"] --> B["Redis"]
```
**Quote labels with special characters.** Parentheses, colons, commas, brackets, and ampersands break the parser when unquoted. Wrap any label containing special characters in double quotes:
```
A["handleRequest(ctx)"] --> B["DB: query users"]
A[handleRequest] --> B[query users]
```
**Keep IDs simple.** Node IDs should be alphanumeric with no spaces or punctuation. Put the readable name in the label, not the ID:
```
userSvc["User Service"] --> authSvc["Auth Service"]
```
**Max 10-12 nodes per Mermaid diagram.** Beyond that, readability collapses even with zoom controls and increased fontSize. For complex architectures (15+ elements), use the **hybrid pattern**: a simple 5-8 node Mermaid overview showing module relationships, followed by CSS Grid cards with detailed function lists. Never cram everything into one diagram. Use `subgraph` blocks to group related nodes when under the limit:
```
subgraph Auth
login --> validate --> token
end
subgraph API
gateway --> router --> handler
end
Auth --> API
```
**Arrow styles for semantic meaning:**
| Arrow | Meaning | Use for |
|-------|---------|---------|
| `-->` | Solid | Primary flow |
| `-.->` | Dotted | Optional, async, or fallback paths |
| `==>` | Thick | Critical or highlighted path |
| `--x` | Cross | Rejected or blocked |
| `-->\|label\|` | Labeled | Decision branches, data descriptions |
**Escape pipes in labels.** If a label contains a literal `|`, use `#124;` (HTML entity) or rephrase to avoid it — pipes delimit edge labels in flowcharts.
**Sequence diagram messages must be plain text.** Unlike flowchart labels, sequence diagram messages (the text after `:`) cannot be quoted or escaped. Curly braces `{}`, square brackets `[]`, angle brackets `<>`, and `&` will silently break the parser and the entire diagram renders as raw text. Write human-readable descriptions, not code:
```
%% WRONG — parser chokes on braces, brackets, ampersand
A->>B: web_search({ queries: [...] })
B->>B: User removes query 2, keeps 1 & 3
B->>S: POST /submit { selected: [0, 2] }
%% RIGHT — plain English, no special characters
A->>B: Call web_search with queries
B->>B: User removes query 2, keeps 1 and 3
B->>S: POST /submit with selected indices
```
**Don't mix diagram syntax.** Each diagram type has its own syntax. `-->` works in flowcharts but not in sequence diagrams (`->>` instead). `:::className` works in flowcharts but not in ER diagrams. When in doubt, check the examples below for correct syntax per type.
### Layout Direction: TD vs LR
`flowchart LR` (left-to-right) spreads horizontally. With many nodes, Mermaid scales everything down to fit the width, making text unreadable. `flowchart TD` (top-down) is almost always better.
**When to use each:**
| Direction | Use when | Avoid when |
|-----------|----------|------------|
| `TD` (top-down) | Complex diagrams, 5+ nodes, hierarchies, architecture | Simple A→B→C linear flows |
| `LR` (left-to-right) | Simple linear flows, 3-4 nodes, pipelines | Complex graphs, many branches |
**Rule of thumb:** If the diagram has more than one row of nodes or any branching, use `TD`. The extra vertical space makes labels readable.
```
%% WRONG — LR with many nodes produces wide, short, unreadable diagram
flowchart LR
A --> B --> C --> D --> E
A --> F --> G --> H
%% RIGHT — TD uses vertical space, labels stay readable
flowchart TD
A --> B --> C --> D --> E
A --> F --> G --> H
```
### Diagram Type Examples
**Flowchart with decisions:**
```html
<pre class="mermaid">
graph TD
A[Request] --> B{Authenticated?}
B -->|Yes| C[Load Dashboard]
B -->|No| D[Login Page]
D --> E[Submit Credentials]
E --> B
C --> F{Role?}
F -->|Admin| G[Admin Panel]
F -->|User| H[User Dashboard]
</pre>
```
**Sequence diagram:**
```html
<pre class="mermaid">
sequenceDiagram
participant C as Client
participant G as Gateway
participant S as Service
participant D as Database
C->>G: POST /api/data
G->>G: Validate JWT
G->>S: Forward request
S->>D: Query
D-->>S: Results
S-->>G: Response
G-->>C: 200 OK
</pre>
```
**ER diagram:**
```html
<pre class="mermaid">
erDiagram
USERS ||--o{ ORDERS : places
ORDERS ||--|{ LINE_ITEMS : contains
LINE_ITEMS }o--|| PRODUCTS : references
USERS { string email PK }
ORDERS { int id PK }
LINE_ITEMS { int quantity }
PRODUCTS { string name }
</pre>
```
**State diagram:**
```html
<pre class="mermaid">
stateDiagram-v2
[*] --> Draft
Draft --> Review : submit
Review --> Approved : approve
Review --> Draft : request_changes
Approved --> Published : publish
Published --> Archived : archive
Archived --> [*]
</pre>
```
**Mind map:**
```html
<pre class="mermaid">
mindmap
root((Project))
Frontend
React
Next.js
Tailwind
Backend
Node.js
PostgreSQL
Redis
Infrastructure
AWS
Docker
Terraform
</pre>
```
**Class diagram:**
```html
<pre class="mermaid">
classDiagram
class User {
+string email
+string name
+login()
+logout()
}
class Order {
+int id
+decimal total
+submit()
}
class Product {
+string name
+decimal price
}
User "1" --> "*" Order : places
Order "*" --> "*" Product : contains
</pre>
```
**C4 architecture (flowchart-as-C4):**
```html
<pre class="mermaid">
graph TD
user("👤 User<br/><small>Browser client</small>")
subgraph boundary["Web Platform"]
app["Web App<br/><small>Node.js</small>"]
db[("Database<br/><small>PostgreSQL</small>")]
end
email["📧 Email Service"]:::ext
payment["💳 Payment Gateway"]:::ext
user -->|"HTTPS"| app
app -->|"SQL"| db
app -->|"SMTP"| email
app -->|"API"| payment
classDef ext fill:none,stroke-dasharray:5 5
</pre>
```
Do NOT use native `C4Context` / `C4Container` syntax — it hardcodes sharp corners, its own font, and inline colors that ignore `themeVariables`. Use `graph TD` + `subgraph` for C4 boundaries instead; it inherits all theme settings automatically.
### Which Mermaid Diagram Type?
Quick-reference for choosing the right Mermaid syntax:
| You want to show... | Use | Syntax keyword |
|---|---|---|
| Process flow, decisions, pipelines | Flowchart | `graph TD` / `graph LR` |
| Request/response, API calls, temporal interactions | Sequence diagram | `sequenceDiagram` |
| Database tables and relationships | ER diagram | `erDiagram` |
| OOP classes, domain models with methods | Class diagram | `classDiagram` |
| System architecture at multiple zoom levels | C4 diagram | `graph TD` + `subgraph` (not native `C4Context`) |
| State transitions, lifecycles | State diagram | `stateDiagram-v2` |
| Hierarchical breakdowns, brainstorms | Mind map | `mindmap` |
### Dark Mode Handling
Mermaid initializes once — it can't reactively switch themes. Read the preference at load time inside your `<script type="module">`:
```javascript
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
// Use isDark to pick light or dark values in themeVariables
```
The CSS overrides on the container (`.mermaid-wrap`) and page will still respond to `prefers-color-scheme` normally — only the Mermaid SVG internals are static.
## Chart.js — Data Visualizations
Use for bar charts, line charts, pie/doughnut charts, radar charts, and other data-driven visualizations in dashboard-type diagrams. Overkill for static numbers — use pure SVG/CSS for simple progress bars and sparklines.
```html
<script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
<canvas id="myChart" width="600" height="300"></canvas>
<script>
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const textColor = isDark ? '#8b949e' : '#6b7280';
const gridColor = isDark ? 'rgba(255,255,255,0.06)' : 'rgba(0,0,0,0.06)';
const fontFamily = getComputedStyle(document.documentElement)
.getPropertyValue('--font-body').trim() || 'system-ui, sans-serif';
new Chart(document.getElementById('myChart'), {
type: 'bar',
data: {
labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
datasets: [{
label: 'Feedback Items',
data: [45, 62, 78, 91, 120],
backgroundColor: isDark ? 'rgba(129, 140, 248, 0.6)' : 'rgba(79, 70, 229, 0.6)',
borderColor: isDark ? '#818cf8' : '#4f46e5',
borderWidth: 1,
borderRadius: 4,
}]
},
options: {
responsive: true,
plugins: {
legend: { labels: { color: textColor, font: { family: fontFamily } } },
},
scales: {
x: { ticks: { color: textColor, font: { family: fontFamily } }, grid: { color: gridColor } },
y: { ticks: { color: textColor, font: { family: fontFamily } }, grid: { color: gridColor } },
}
}
});
</script>
```
Wrap the canvas in a styled container:
```css
.chart-container {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 10px;
padding: 20px;
position: relative;
}
.chart-container canvas {
max-height: 300px;
}
```
## anime.js — Orchestrated Animations
Use when a diagram has 10+ elements and you want a choreographed entrance sequence (staggered reveals, path drawing, count-up numbers). For simpler diagrams, CSS `animation-delay` staggering is sufficient.
```html
<script src="https://cdn.jsdelivr.net/npm/[email protected]/lib/anime.min.js"></script>
<script>
const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
if (!prefersReduced) {
anime({
targets: '.ve-card',
opacity: [0, 1],
translateY: [20, 0],
delay: anime.stagger(80, { start: 200 }),
easing: 'easeOutCubic',
duration: 500,
});
anime({
targets: '.connector path',
strokeDashoffset: [anime.setDashoffset, 0],
easing: 'easeInOutCubic',
duration: 800,
delay: anime.stagger(150, { start: 600 }),
});
document.querySelectorAll('[data-count]').forEach(el => {
anime({
targets: { val: 0 },
val: parseInt(el.dataset.count),
round: 1,
duration: 1200,
delay: 400,
easing: 'easeOutExpo',
update: (anim) => { el.textContent = anim.animations[0].currentValue; }
});
});
}
</script>
```
When using anime.js, set initial opacity to 0 in CSS so elements don't flash before the animation:
```css
.ve-card { opacity: 0; }
@media (prefers-reduced-motion: reduce) {
.ve-card { opacity: 1 !important; }
}
```
## Google Fonts — Typography
Always load with `display=swap` for fast rendering. Pick a distinctive pairing — body + mono at minimum, optionally a display font for the title.
**FORBIDDEN as `--font-body` (AI slop signals):**
- Inter — the single most overused AI default font
- Roboto — generic Android/Google default
- Arial, Helvetica — system defaults with no character
- system-ui alone without a named font — signals zero design intent
```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&family=Outfit:wght@400;500;600;700&display=swap" rel="stylesheet">
```
Define as CSS variables for easy reference:
```css
:root {
--font-body: 'Outfit', system-ui, sans-serif;
--font-mono: 'Space Mono', 'SF Mono', Consolas, monospace;
}
```
**Font pairings** (rotate — never use the same pairing twice in a row):
| Body / Headings | Mono / Labels | Feel | Use for |
|---|---|---|---|
| DM Sans | Fira Code | Friendly, developer | Blueprint, technical docs |
| Instrument Serif | JetBrains Mono | Editorial, refined | Plan reviews, decision logs |
| IBM Plex Sans | IBM Plex Mono | Reliable, readable | Architecture diagrams |
| Bricolage Grotesque | Fragment Mono | Bold, characterful | Data tables, dashboards |
| Plus Jakarta Sans | Azeret Mono | Rounded, approachable | Status reports, audits |
| Outfit | Space Mono | Clean geometric, modern | Flowcharts, pipelines |
| Sora | IBM Plex Mono | Technical, precise | ER diagrams, schemas |
| Crimson Pro | Noto Sans Mono | Scholarly, serious | RFC reviews, specs |
| Fraunces | Source Code Pro | Warm, distinctive | Project recaps |
| Geist | Geist Mono | Vercel-inspired, sharp | Modern API docs |
| Red Hat Display | Red Hat Mono | Cohesive family | System overviews |
| Libre Franklin | Inconsolata | Classic, reliable | Data-dense tables |
| Playfair Display | Roboto Mono | Elegant contrast | Executive summaries |
The first 5 pairings are recommended for most use cases. Vary across consecutive diagrams.
### Typography by Content Voice
For prose-heavy pages (documentation, articles, essays), match typography to the content's voice:
| Voice | Fonts | Best For |
|-------|-------|----------|
| **Literary / Thoughtful** | Literata, Lora, Newsreader, Merriweather | Essays, personal posts, long-form articles |
| **Technical / Precise** | IBM Plex Sans + Mono, Geist + Geist Mono, Source family | Documentation, READMEs, API references |
| **Bold / Contemporary** | Bricolage Grotesque, Space Grotesk, DM Sans | Product pages, feature announcements |
| **Minimal / Focused** | Source Serif 4 + Source Sans 3, Karla + Inconsolata | Tutorials, how-tos, focused reading |
**Literata** deserves special mention — it has optical sizing designed specifically for screen reading. Google's answer to Georgia, but modernized.
# Responsive Section Navigation
Navigation pattern for multi-section pages (reviews, recaps, dashboards). Provides a sticky sidebar TOC on desktop and a sticky horizontal scrollable bar on mobile.
## Layout Structure
The page uses a two-column CSS Grid: sidebar (TOC) + main content. On mobile it collapses to single-column with the TOC becoming a horizontal bar.
```html
<body>
<div class="wrap">
<nav class="toc" id="toc">
<div class="toc-title">Contents</div>
<a href="#s1">1. First Section</a>
<a href="#s2">2. Second Section</a>
<!-- one link per section -->
</nav>
<div class="main">
<h1>Page Title</h1>
<p class="subtitle">Subtitle text</p>
<div id="s1" class="sec-head ...">1 — First Section</div>
<!-- section content -->
<div id="s2" class="sec-head ...">2 — Second Section</div>
<!-- section content -->
</div><!-- /main -->
</div><!-- /wrap -->
</body>
```
Key structural rules:
- `<nav class="toc">` is the **first child** of `.wrap`
- All page content goes inside `<div class="main">`
- Every section heading gets an `id="s1"`, `id="s2"`, etc.
- TOC links use `href="#s1"` matching those IDs
- Keep TOC link text short (truncate long section names)
## CSS
### Wrap (grid layout)
```css
.wrap {
max-width: 1400px;
margin: 0 auto;
display: grid;
grid-template-columns: 170px 1fr;
gap: 0 40px;
}
.main { min-width: 0; }
```
### TOC — Desktop (sticky sidebar)
```css
.toc {
position: sticky;
top: 24px;
align-self: start;
padding: 14px 0;
grid-row: 1 / -1;
max-height: calc(100dvh - 48px);
overflow-y: auto;
}
.toc::-webkit-scrollbar { width: 3px; }
.toc::-webkit-scrollbar-thumb { background: var(--surface-elevated); border-radius: 2px; }
.toc-title {
font-family: var(--font-mono);
font-size: 9px;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 2px;
color: var(--text-dim);
padding: 0 0 10px;
margin-bottom: 8px;
border-bottom: 1px solid var(--border);
}
.toc a {
display: block;
font-size: 11px;
color: var(--text-dim);
text-decoration: none;
padding: 4px 8px;
border-radius: 5px;
border-left: 2px solid transparent;
transition: all 0.15s;
line-height: 1.4;
margin-bottom: 1px;
}
.toc a:hover { color: var(--text); background: var(--surface2); }
.toc a.active { color: var(--text); border-left-color: var(--accent); }
```
Replace `var(--accent)` with your page's primary accent color variable (e.g., `var(--orange)`, `var(--blue)`).
### TOC — Mobile (sticky horizontal bar)
```css
@media (max-width: 1000px) {
.wrap { grid-template-columns: 1fr; padding-top: 0; }
body { padding-top: 0; }
.toc {
position: sticky;
top: 0;
z-index: 200;
max-height: none;
display: flex;
gap: 4px;
align-items: center;
overflow-x: auto;
-webkit-overflow-scrolling: touch;
background: var(--bg);
border-bottom: 1px solid var(--border);
padding: 10px 0;
margin: 0 -40px;
padding-left: 40px;
padding-right: 40px;
grid-row: auto;
}
.toc::-webkit-scrollbar { display: none; }
.toc-title { display: none; }
.toc a {
white-space: nowrap;
flex-shrink: 0;
border-left: none;
border-bottom: 2px solid transparent;
border-radius: 4px 4px 0 0;
padding: 6px 10px;
font-size: 10px;
}
.toc a.active {
border-left: none;
border-bottom-color: var(--accent);
background: var(--surface);
}
.main { padding-top: 20px; }
/* Offset scroll target so headings clear the sticky bar */
.sec-head { scroll-margin-top: 52px; }
}
```
Adjust `margin: 0 -40px` and `padding-left/right: 40px` to match your `body` padding so the bar bleeds edge-to-edge.
## JavaScript — Scroll Spy
Place before `</body>`, after any Mermaid init:
```html
<script>
(function() {
const toc = document.getElementById('toc');
const links = toc.querySelectorAll('a');
const sections = [];
links.forEach(link => {
const id = link.getAttribute('href').slice(1);
const el = document.getElementById(id);
if (el) sections.push({ id, el, link });
});
const observer = new IntersectionObserver(entries => {
entries.forEach(entry => {
if (entry.isIntersecting) {
links.forEach(l => l.classList.remove('active'));
const match = sections.find(s => s.el === entry.target);
if (match) {
match.link.classList.add('active');
// On mobile, auto-scroll the active tab into view
if (window.innerWidth <= 1000) {
match.link.scrollIntoView({
behavior: 'smooth', block: 'nearest', inline: 'center'
});
}
}
}
});
}, { rootMargin: '-10% 0px -80% 0px' });
sections.forEach(s => observer.observe(s.el));
links.forEach(link => {
link.addEventListener('click', e => {
e.preventDefault();
const id = link.getAttribute('href').slice(1);
const el = document.getElementById(id);
if (el) {
el.scrollIntoView({ behavior: 'smooth', block: 'start' });
history.replaceState(null, '', '#' + id);
}
});
});
})();
</script>
```
## Adaptation Notes
- The `.toc-title` text, link labels, accent color, and section IDs change per page. Everything else is copy-paste.
- For pages with fewer than 4 sections, skip the TOC entirely — it adds clutter without value.
- The `grid-template-columns: 170px 1fr` width works for most TOCs. If section names are longer, go up to `200px`.
- The `rootMargin: '-10% 0px -80% 0px'` means a section is "active" when its heading enters the top 10-20% of the viewport. This works well with sticky headers.
- On mobile, the horizontal bar uses `overflow-x: auto` with hidden scrollbar. The active tab auto-scrolls into the center of the bar as the user scrolls the page.
# Slide Deck Patterns
CSS patterns, JS engine, slide type layouts, transitions, navigation chrome, and curated presets for self-contained HTML slide presentations. All slides are viewport-fit (100dvh), single-file, same philosophy as scrollable pages.
**When to use slides:** Only when the user explicitly requests them — `/generate-slides`, `--slides` flag on an existing prompt, or natural language like "as a slide deck." Never auto-select slide format.
**Before generating**, also read `./css-patterns.md` for shared patterns (Mermaid zoom controls, overflow protection, depth tiers, status badges) and `./libraries.md` for Mermaid theming, Chart.js, and font pairings. Those patterns apply to slides too — this file adds slide-specific patterns on top.
## Planning a Deck from a Source Document
When converting a plan, spec, review, or any structured document into slides, follow this process before writing any HTML. Skipping it leads to polished-looking decks that silently drop 30–40% of the source material.
**Step 1 — Inventory the source.** Read the entire source document and enumerate every section, subsection, card, table row, decision, specification, collapsible detail, and footnote. Count them. A plan with 7 sections, 6 decision cards, a 7-row file table, 4 presets, 6 technique guides, and an engine spec with 3 sub-specs and 2 collapsibles is ~25 distinct content items that all need slide real estate.
**Step 2 — Map source to slides.** Assign each inventory item to one or more slides. Every item must appear somewhere. Rules:
- If a section has 6 decisions, all 6 need slides — not the 2 that fit on one split slide.
- If a table has 7 rows, all 7 rows show up.
- Collapsible/expandable details in the source are not optional in the deck — they become their own slides.
- Subsections with multiple cards (e.g., "6 Visual Technique cards") may need 2–3 slides to cover at readable density.
- Each plan section typically needs a divider slide + 1–3 content slides depending on density.
**Step 3 — Choose layouts.** For each planned slide, pick a slide type and spatial composition. Vary across the sequence (see Compositional Variety below). This is where narrative pacing happens — alternate dense slides with sparse ones.
**Step 4 — Plan images.** Run `which surf`. If surf-cli is available, plan 2–4 generated images for the deck. At minimum, target the **title slide** (16:9 background that sets the visual tone) and **one full-bleed slide** (immersive background for a key moment). Content slides with conceptual topics also benefit from a 1:1 illustration in the aside area. Generate these images early — before writing HTML — so you can embed them as base64 data URIs. See the Proactive Imagery section below for the full workflow. If surf isn't available, degrade to CSS gradients and SVG decorations — note the fallback in a comment but don't error.
**Step 5 — Verify before writing HTML.** Scan the inventory from Step 1. Is anything unmapped? Would a reader of the source document notice something missing from the deck? If yes, add slides. A source document with 7 sections typically produces 18–25 slides, not 10–13.
**The test:** After generating the deck, a reader who has never seen the source document should be able to reconstruct every major point from the slides alone. If they'd miss entire sections, the deck is incomplete.
## Slide Engine Base
The deck is a scroll-snap container. Each slide is exactly one viewport tall.
```html
<body>
<div class="deck">
<section class="slide slide--title"> ... </section>
<section class="slide slide--content"> ... </section>
<section class="slide slide--diagram"> ... </section>
<!-- one <section> per slide -->
</div>
</body>
```
```css
/* Scroll-snap container */
.deck {
height: 100dvh;
overflow-y: auto;
scroll-snap-type: y mandatory;
scroll-behavior: smooth;
-webkit-overflow-scrolling: touch;
}
/* Individual slide */
.slide {
height: 100dvh;
scroll-snap-align: start;
overflow: hidden;
position: relative;
display: flex;
flex-direction: column;
justify-content: center;
padding: clamp(40px, 6vh, 80px) clamp(40px, 8vw, 120px);
isolation: isolate; /* contain z-index stacking */
}
```
## Typography Scale
Slide typography is 2–3× larger than scrollable pages. Page-sized text on a viewport-sized canvas looks like a mistake.
```css
.slide__display {
font-size: clamp(48px, 10vw, 120px);
font-weight: 800;
letter-spacing: -3px;
line-height: 0.95;
text-wrap: balance;
}
.slide__heading {
font-size: clamp(28px, 5vw, 48px);
font-weight: 700;
letter-spacing: -1px;
line-height: 1.1;
text-wrap: balance;
}
.slide__body {
font-size: clamp(16px, 2.2vw, 24px);
line-height: 1.6;
text-wrap: pretty;
}
.slide__label {
font-family: var(--font-mono);
font-size: clamp(10px, 1.2vw, 14px);
font-weight: 600;
text-transform: uppercase;
letter-spacing: 1.5px;
color: var(--text-dim);
}
.slide__subtitle {
font-family: var(--font-mono);
font-size: clamp(14px, 1.8vw, 20px);
color: var(--text-dim);
letter-spacing: 0.5px;
}
```
| Element | Size range | Notes |
|---------|-----------|-------|
| Display (title slides) | 48–120px | `10vw` preferred, weight 800 |
| Section numbers | 100–240px | Ultra-light (weight 200), decorative |
| Headings | 28–48px | `5vw` preferred, weight 700 |
| Body / bullets | 16–24px | `2.2vw` preferred, 1.6 line-height |
| Code blocks | 14–18px | `1.8vw` preferred, mono |
| Quotes | 24–48px | `4vw` preferred, serif italic |
| Labels / captions | 10–14px | Mono, uppercase, dimmed |
## Cinematic Transitions
IntersectionObserver adds `.visible` when a slide enters the viewport. Slides animate in once and stay visible when scrolling back.
```css
/* Slide entrance — fade + lift + subtle scale */
.slide {
opacity: 0;
transform: translateY(40px) scale(0.98);
transition:
opacity 0.6s cubic-bezier(0.16, 1, 0.3, 1),
transform 0.6s cubic-bezier(0.16, 1, 0.3, 1);
}
.slide.visible {
opacity: 1;
transform: none;
}
/* Staggered child reveals — add .reveal to each content element */
.slide .reveal {
opacity: 0;
transform: translateY(20px);
transition:
opacity 0.5s cubic-bezier(0.16, 1, 0.3, 1),
transform 0.5s cubic-bezier(0.16, 1, 0.3, 1);
}
.slide.visible .reveal {
opacity: 1;
transform: none;
}
/* Stagger delays — up to 6 children per slide */
.slide.visible .reveal:nth-child(1) { transition-delay: 0.1s; }
.slide.visible .reveal:nth-child(2) { transition-delay: 0.2s; }
.slide.visible .reveal:nth-child(3) { transition-delay: 0.3s; }
.slide.visible .reveal:nth-child(4) { transition-delay: 0.4s; }
.slide.visible .reveal:nth-child(5) { transition-delay: 0.5s; }
.slide.visible .reveal:nth-child(6) { transition-delay: 0.6s; }
@media (prefers-reduced-motion: reduce) {
.slide,
.slide .reveal {
opacity: 1 !important;
transform: none !important;
transition: none !important;
}
}
```
## Navigation Chrome
All navigation is `position: fixed` with high z-index, layered above slides. Styled to be visible on any background.
### Progress Bar
```css
.deck-progress {
position: fixed;
top: 0;
left: 0;
height: 3px;
background: var(--accent);
z-index: 100;
transition: width 0.3s ease;
pointer-events: none;
}
```
### Nav Dots
```css
.deck-dots {
position: fixed;
right: clamp(12px, 2vw, 24px);
top: 50%;
transform: translateY(-50%);
display: flex;
flex-direction: column;
gap: 8px;
z-index: 100;
}
.deck-dot {
width: 8px;
height: 8px;
border-radius: 50%;
background: var(--text-dim);
opacity: 0.3;
border: none;
padding: 0;
cursor: pointer;
transition: opacity 0.2s ease, transform 0.2s ease;
}
.deck-dot:hover {
opacity: 0.6;
}
.deck-dot.active {
opacity: 1;
transform: scale(1.5);
background: var(--accent);
}
```
### Slide Counter
```css
.deck-counter {
position: fixed;
bottom: clamp(12px, 2vh, 24px);
right: clamp(12px, 2vw, 24px);
font-family: var(--font-mono);
font-size: 12px;
color: var(--text-dim);
z-index: 100;
font-variant-numeric: tabular-nums;
}
```
### Keyboard Hints
Auto-fade after first interaction or after 4 seconds.
```css
.deck-hints {
position: fixed;
bottom: clamp(12px, 2vh, 24px);
left: 50%;
transform: translateX(-50%);
font-family: var(--font-mono);
font-size: 11px;
color: var(--text-dim);
opacity: 0.6;
z-index: 100;
transition: opacity 0.5s ease;
white-space: nowrap;
}
.deck-hints.faded {
opacity: 0;
pointer-events: none;
}
```
### Chrome Visibility on Mixed Backgrounds
For decks where some slides are light and some dark (especially full-bleed slides), nav chrome needs to remain visible. Two approaches:
```css
/* Approach A: subtle backdrop on chrome elements */
.deck-dots,
.deck-counter {
background: color-mix(in srgb, var(--bg) 70%, transparent 30%);
padding: 6px;
border-radius: 20px;
backdrop-filter: blur(4px);
-webkit-backdrop-filter: blur(4px);
}
/* Approach B: text shadow for legibility on any background */
.deck-counter,
.deck-hints {
text-shadow: 0 1px 3px rgba(0, 0, 0, 0.3);
}
```
## SlideEngine JavaScript
Add once at the end of the page. Handles navigation, chrome updates, and scroll-triggered reveals. Event delegation ensures slide-internal interactions (Mermaid zoom, scrollable code, overflow tables) don't trigger slide navigation.
```javascript
class SlideEngine {
constructor() {
this.deck = document.querySelector('.deck');
this.slides = [...document.querySelectorAll('.slide')];
this.current = 0;
this.total = this.slides.length;
this.buildChrome();
this.bindEvents();
this.observe();
this.update();
}
buildChrome() {
// Progress bar
var bar = document.createElement('div');
bar.className = 'deck-progress';
document.body.appendChild(bar);
this.bar = bar;
// Nav dots
var dots = document.createElement('div');
dots.className = 'deck-dots';
var self = this;
this.slides.forEach(function(_, i) {
var d = document.createElement('button');
d.className = 'deck-dot';
d.title = 'Slide ' + (i + 1);
d.onclick = function() { self.goTo(i); };
dots.appendChild(d);
});
document.body.appendChild(dots);
this.dots = [].slice.call(dots.children);
// Counter
var ctr = document.createElement('div');
ctr.className = 'deck-counter';
document.body.appendChild(ctr);
this.counter = ctr;
// Keyboard hints
var hints = document.createElement('div');
hints.className = 'deck-hints';
hints.textContent = '\u2190 \u2192 or scroll to navigate';
document.body.appendChild(hints);
this.hints = hints;
this.hintTimer = setTimeout(function() {
hints.classList.add('faded');
}, 4000);
}
bindEvents() {
var self = this;
// Keyboard — skip if focus is inside interactive content
document.addEventListener('keydown', function(e) {
if (e.target.closest('.mermaid-wrap, .table-scroll, .code-scroll, input, textarea, [contenteditable]')) return;
if (['ArrowDown', 'ArrowRight', ' ', 'PageDown'].includes(e.key)) {
e.preventDefault(); self.next();
} else if (['ArrowUp', 'ArrowLeft', 'PageUp'].includes(e.key)) {
e.preventDefault(); self.prev();
} else if (e.key === 'Home') {
e.preventDefault(); self.goTo(0);
} else if (e.key === 'End') {
e.preventDefault(); self.goTo(self.total - 1);
}
self.fadeHints();
});
// Touch swipe
var touchY;
this.deck.addEventListener('touchstart', function(e) {
touchY = e.touches[0].clientY;
}, { passive: true });
this.deck.addEventListener('touchend', function(e) {
var dy = touchY - e.changedTouches[0].clientY;
if (Math.abs(dy) > 50) { dy > 0 ? self.next() : self.prev(); }
});
}
observe() {
var self = this;
var obs = new IntersectionObserver(function(entries) {
entries.forEach(function(entry) {
if (entry.isIntersecting) {
entry.target.classList.add('visible');
self.current = self.slides.indexOf(entry.target);
self.update();
}
});
}, { threshold: 0.5 });
this.slides.forEach(function(s) { obs.observe(s); });
}
goTo(i) {
this.slides[Math.max(0, Math.min(i, this.total - 1))]
.scrollIntoView({ behavior: 'smooth' });
}
next() { if (this.current < this.total - 1) this.goTo(this.current + 1); }
prev() { if (this.current > 0) this.goTo(this.current - 1); }
update() {
this.bar.style.width = ((this.current + 1) / this.total * 100) + '%';
var self = this;
this.dots.forEach(function(d, i) { d.classList.toggle('active', i === self.current); });
this.counter.textContent = (this.current + 1) + ' / ' + this.total;
}
fadeHints() {
clearTimeout(this.hintTimer);
this.hints.classList.add('faded');
}
}
```
**Usage:** Instantiate after the DOM is ready and any libraries (Mermaid, Chart.js) have rendered. Always call `autoFit()` before `new SlideEngine()` so content is sized correctly before intersection observers fire.
```html
<script>
// After Mermaid/Chart.js initialization (if used), or at end of <body>:
document.addEventListener('DOMContentLoaded', function() {
autoFit();
new SlideEngine();
});
</script>
```
## Auto-Fit
A single post-render function that handles all known content overflow cases. Agents can't perfectly predict how text reflows at every viewport size, so `autoFit()` is a required safety net. Call it after Mermaid/Chart.js render but before SlideEngine init.
```javascript
function autoFit() {
// Mermaid SVGs: fill container instead of rendering at intrinsic size
document.querySelectorAll('.mermaid svg').forEach(function(svg) {
svg.removeAttribute('height');
svg.style.width = '100%';
svg.style.maxWidth = '100%';
svg.style.height = 'auto';
svg.parentElement.style.width = '100%';
});
// KPI values: visually scale down text that overflows card width
document.querySelectorAll('.slide__kpi-val').forEach(function(el) {
if (el.scrollWidth > el.clientWidth) {
var s = el.clientWidth / el.scrollWidth;
el.style.transform = 'scale(' + s + ')';
el.style.transformOrigin = 'left top';
}
});
// Blockquotes: reduce font proportionally for long text
document.querySelectorAll('.slide--quote blockquote').forEach(function(el) {
var len = el.textContent.trim().length;
if (len > 100) {
var scale = Math.max(0.5, 100 / len);
var fs = parseFloat(getComputedStyle(el).fontSize);
el.style.fontSize = Math.max(16, Math.round(fs * scale)) + 'px';
}
});
}
```
Three cases, one function:
- **Mermaid:** SVGs render with fixed dimensions inside flex containers — force them to fill available width.
- **KPI values:** Long text strings at hero scale overflow card boundaries — `transform: scale()` shrinks visually without reflow.
- **Blockquotes:** Quotes longer than ~100 characters get proportionally smaller font. The 0.5 floor prevents unreadably small text; if it needs more than 50% shrink, it should have been a content slide.
## Slide Type Layouts
Each type has a defined HTML structure and CSS layout. The agent can adapt colors, fonts, and spacing per aesthetic, but the structural patterns stay consistent.
### Title Slide
Full-viewport hero. Background treatment via gradient, texture, or surf-generated image. 80–120px display type.
```html
<section class="slide slide--title">
<svg class="slide__decor" ...><!-- optional decorative accent --></svg>
<div class="slide__content reveal">
<h1 class="slide__display">Deck Title</h1>
<p class="slide__subtitle reveal">Subtitle or date</p>
</div>
</section>
```
```css
.slide--title {
justify-content: center;
align-items: center;
text-align: center;
}
```
### Section Divider
Oversized decorative number (200px+, ultra-light weight) with heading. Breathing room between topics. SVG accent marks optional.
```html
<section class="slide slide--divider">
<span class="slide__number">02</span>
<div class="slide__content">
<h2 class="slide__heading reveal">Section Title</h2>
<p class="slide__subtitle reveal">Optional subheading</p>
</div>
</section>
```
```css
.slide--divider {
justify-content: center;
}
.slide--divider .slide__number {
font-size: clamp(100px, 22vw, 260px);
font-weight: 200;
line-height: 0.85;
opacity: 0.08;
position: absolute;
top: 50%;
left: 50%;
transform: translate(-50%, -55%);
pointer-events: none;
font-variant-numeric: tabular-nums;
}
```
### Content Slide
Heading + bullets or paragraphs. Asymmetric layout — content offset to one side. Max 5–6 bullets (2 lines each).
```html
<section class="slide slide--content">
<div class="slide__inner">
<div class="slide__text">
<h2 class="slide__heading reveal">Heading</h2>
<ul class="slide__bullets">
<li class="reveal">First point</li>
<li class="reveal">Second point</li>
</ul>
</div>
<div class="slide__aside reveal">
<!-- optional: illustration, icon, mini-diagram, accent SVG -->
</div>
</div>
</section>
```
```css
.slide--content .slide__inner {
display: grid;
grid-template-columns: 3fr 2fr;
gap: clamp(24px, 4vw, 60px);
align-items: center;
width: 100%;
}
/* For right-heavy variant: swap to 2fr 3fr */
.slide--content .slide__bullets {
list-style: none;
padding: 0;
}
.slide--content .slide__bullets li {
padding: 8px 0 8px 20px;
position: relative;
font-size: clamp(16px, 2vw, 22px);
line-height: 1.6;
color: var(--text-dim);
}
.slide--content .slide__bullets li::before {
content: '';
position: absolute;
left: 0;
top: 18px;
width: 6px;
height: 6px;
border-radius: 50%;
background: var(--accent);
}
```
### Split Slide
Asymmetric two-panel (60/40 or 70/30). Before/after, text+diagram, text+image. Each panel has its own background tier. Zero padding on the slide itself — panels fill edge to edge.
```html
<section class="slide slide--split">
<div class="slide__panels">
<div class="slide__panel slide__panel--primary">
<h2 class="slide__heading reveal">Left Panel</h2>
<div class="slide__body reveal">Content...</div>
</div>
<div class="slide__panel slide__panel--secondary">
<!-- diagram, image, code block, or contrasting content -->
</div>
</div>
</section>
```
```css
.slide--split {
padding: 0;
}
.slide--split .slide__panels {
display: grid;
grid-template-columns: 3fr 2fr;
height: 100%;
}
.slide--split .slide__panel {
padding: clamp(40px, 6vh, 80px) clamp(32px, 4vw, 60px);
display: flex;
flex-direction: column;
justify-content: center;
}
.slide--split .slide__panel--primary {
background: var(--surface);
}
.slide--split .slide__panel--secondary {
background: var(--surface2);
}
```
### Diagram Slide
Full-viewport Mermaid diagram. Max 8–10 nodes (presentation scale — fewer, larger than page diagrams). Node labels at 18px+, edges at 2px+. Zoom controls from `css-patterns.md` apply here.
**When to use Mermaid vs CSS in slides.** Mermaid renders SVGs at a fixed size the agent can't control — node dimensions are set by the library, not by CSS. This creates a recurring problem: small diagrams (fewer than ~7 nodes, no branching) render as tiny elements floating in a huge viewport with acres of dead space. The rule:
- **Use Mermaid** for complex graphs: 8+ nodes, branching paths, cycles, multiple edge crossings — anything where automatic edge routing saves real effort.
- **Use CSS Pipeline** (below) for simple linear flows: A → B → C → D sequences, build steps, deployment stages. CSS cards give full control over sizing, typography, and fill the viewport naturally.
- **Never leave a small Mermaid diagram alone on a slide.** If the diagram is small, either switch to CSS, or pair it with supporting content (description cards, bullet annotations, a summary panel) in a split layout. A slide with a tiny diagram and empty space is a failed slide.
**Mermaid centering fix.** When you do use Mermaid, add `display: flex; align-items: center; justify-content: center;` to `.mermaid-wrap` so the SVG centers within its container instead of hugging the top-left corner. Change `transform-origin` to `center center` so zoom radiates from the middle.
```html
<section class="slide slide--diagram">
<h2 class="slide__heading reveal">Diagram Title</h2>
<div class="mermaid-wrap reveal" style="flex:1; min-height:0;">
<div class="zoom-controls">
<button onclick="zoomDiagram(this,1.2)" title="Zoom in">+</button>
<button onclick="zoomDiagram(this,0.8)" title="Zoom out">−</button>
<button onclick="resetZoom(this)" title="Reset">↺</button>
<button onclick="openDiagramFullscreen(this)" title="Open full size in new tab">⛶</button>
</div>
<pre class="mermaid">
graph TD
A --> B
</pre>
</div>
</section>
```
**Click to expand.** Clicking anywhere on the diagram (without dragging) opens it full-size in a new browser tab. The expand button (⛶) provides the same functionality for discoverability.
```css
.slide--diagram {
padding: clamp(24px, 4vh, 48px) clamp(24px, 4vw, 60px);
}
.slide--diagram .slide__heading {
margin-bottom: clamp(8px, 1.5vh, 20px);
}
.slide--diagram .mermaid-wrap {
border-radius: 12px;
overflow: auto;
display: flex;
align-items: center;
justify-content: center;
}
.slide--diagram .mermaid-wrap .mermaid {
transform-origin: center center;
}
```
**Auto-fit SVG to container.** Mermaid renders SVGs with fixed dimensions and an inline `max-width` style that keeps diagrams tiny inside large slides. The `autoFit()` function (see above) handles this at runtime. Keep the CSS as a belt-and-suspenders fallback:
```css
.slide--diagram .mermaid svg {
width: 100% !important;
height: auto !important;
max-width: 100% !important;
}
```
**Mermaid overrides for presentation scale** (add alongside the standard Mermaid CSS overrides from `libraries.md`):
```css
.slide--diagram .mermaid .nodeLabel {
font-size: 18px !important;
}
.slide--diagram .mermaid .edgeLabel {
font-size: 14px !important;
}
.slide--diagram .mermaid .node rect,
.slide--diagram .mermaid .node circle,
.slide--diagram .mermaid .node polygon {
stroke-width: 2px;
}
.slide--diagram .mermaid .edge-pattern-solid {
stroke-width: 2px;
}
```
### CSS Pipeline Slide
For simple linear flows (build steps, deployment stages, data pipelines) where Mermaid would render too small. CSS cards with arrow connectors give full control over sizing and fill the viewport naturally. Each step card expands to fill available space via `flex: 1`.
```html
<section class="slide" style="background-image:radial-gradient(...);">
<p class="slide__label reveal">Pipeline Label</p>
<h2 class="slide__heading reveal">Pipeline Title</h2>
<div class="pipeline reveal">
<div class="pipeline__step" style="border-top-color:var(--accent);">
<div class="pipeline__num">01</div>
<div class="pipeline__name">Step Name</div>
<div class="pipeline__desc">What this step produces or does</div>
<div class="pipeline__file">output-file.md</div>
</div>
<div class="pipeline__arrow">
<svg viewBox="0 0 24 24" width="20" height="20"><path d="M5 12h14m-4-4l4 4-4 4" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>
</div>
<div class="pipeline__step"> ... </div>
<!-- repeat step + arrow pairs -->
</div>
</section>
```
```css
.pipeline {
display: flex;
align-items: stretch;
gap: 0;
flex: 1;
min-height: 0;
margin-top: clamp(12px, 2vh, 24px);
}
.pipeline__step {
flex: 1;
background: var(--surface);
border: 1px solid var(--border);
border-top: 3px solid var(--accent);
border-radius: 10px;
padding: clamp(14px, 2.5vh, 28px) clamp(12px, 1.5vw, 22px);
display: flex;
flex-direction: column;
min-width: 0;
overflow-wrap: break-word;
}
.pipeline__num {
font-size: clamp(10px, 1.2vw, 13px);
font-weight: 600;
color: var(--accent);
letter-spacing: 1px;
}
.pipeline__name {
font-size: clamp(16px, 2vw, 24px);
font-weight: 700;
margin: clamp(4px, 0.8vh, 8px) 0;
}
.pipeline__desc {
font-size: clamp(12px, 1.3vw, 16px);
color: var(--text-dim);
line-height: 1.5;
flex: 1;
}
.pipeline__file {
font-size: clamp(10px, 1.1vw, 12px);
color: var(--accent);
background: var(--accent-dim);
padding: 3px 8px;
border-radius: 4px;
margin-top: clamp(8px, 1.5vh, 16px);
align-self: flex-start;
}
.pipeline__arrow {
display: flex;
align-items: center;
padding: 0 clamp(3px, 0.4vw, 6px);
color: var(--accent);
flex-shrink: 0;
opacity: 0.4;
}
@media (max-width: 768px) {
.pipeline { flex-direction: column; }
.pipeline__arrow { justify-content: center; padding: 4px 0; transform: rotate(90deg); }
}
```
Each `.pipeline__step` uses `flex: 1` to fill available width equally, and the pipeline container itself uses `flex: 1` to fill available vertical space in the slide. Step cards stretch to fill, so the content isn't floating in empty space. The `.pipeline__file` badge at the bottom anchors each card and adds a practical detail. Max 5–6 steps — beyond that, split across two slides.
### Dashboard Slide
KPI cards at presentation scale (48–64px hero numbers). Mini-charts via Chart.js or SVG sparklines. Max 6 KPIs.
```html
<section class="slide slide--dashboard">
<h2 class="slide__heading reveal">Metrics Overview</h2>
<div class="slide__kpis">
<div class="slide__kpi reveal">
<div class="slide__kpi-val" style="color:var(--accent)">247</div>
<div class="slide__kpi-label">Lines Added</div>
</div>
<!-- more KPI cards -->
</div>
</section>
```
```css
.slide--dashboard .slide__kpis {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(clamp(140px, 20vw, 220px), 1fr));
gap: clamp(12px, 2vw, 24px);
}
.slide__kpi {
background: var(--surface);
border: 1px solid var(--border);
border-radius: 12px;
padding: clamp(16px, 3vh, 32px) clamp(16px, 2vw, 24px);
min-width: 0;
overflow: hidden;
}
.slide__kpi-val {
font-size: clamp(36px, 6vw, 64px);
font-weight: 800;
letter-spacing: -1.5px;
line-height: 1.1;
font-variant-numeric: tabular-nums;
white-space: nowrap;
}
.slide__kpi-label {
font-family: var(--font-mono);
font-size: clamp(9px, 1.2vw, 13px);
font-weight: 600;
text-transform: uppercase;
letter-spacing: 1.5px;
color: var(--text-dim);
margin-top: 8px;
}
```
**KPI hero values should be short** — numbers, percentages, 1–3 word labels. Ideal length is 1–6 characters at hero scale. Longer strings like `store=false` break the layout at 64px. If you must show a longer value, put it in the label or body text instead. The `autoFit()` function (see below) will scale down overflows as a safety net.
### Table Slide
18–20px cell text for projection readability. Max 8 rows per slide — overflow paginates to the next slide. Stronger alternating row contrast than page tables.
```html
<section class="slide slide--table">
<h2 class="slide__heading reveal">Data Title</h2>
<div class="table-wrap reveal" style="flex:1; min-height:0;">
<div class="table-scroll">
<table class="data-table"> ... </table>
</div>
</div>
</section>
```
```css
.slide--table {
padding: clamp(24px, 4vh, 48px) clamp(24px, 4vw, 60px);
}
.slide--table .data-table {
font-size: clamp(14px, 1.8vw, 20px);
}
.slide--table .data-table th {
font-size: clamp(10px, 1.3vw, 14px);
padding: clamp(8px, 1.5vh, 14px) clamp(12px, 2vw, 20px);
}
.slide--table .data-table td {
padding: clamp(10px, 1.5vh, 16px) clamp(12px, 2vw, 20px);
}
```
### Code Slide
18px mono on a recessed dark background. Max 10 lines. Floating filename label. Centered on the viewport for focus.
```html
<section class="slide slide--code">
<h2 class="slide__heading reveal">What Changed</h2>
<div class="slide__code-block reveal">
<span class="slide__code-filename">worker.ts</span>
<pre><code>function processQueue(items) {
// highlighted code here
}</code></pre>
</div>
</section>
```
```css
.slide--code {
align-items: center;
}
.slide__code-block {
background: var(--code-bg, #1a1a2e);
border: 1px solid var(--border);
border-radius: 12px;
padding: clamp(24px, 4vh, 48px) clamp(24px, 4vw, 48px);
max-width: 900px;
width: 100%;
position: relative;
}
.slide__code-filename {
position: absolute;
top: -12px;
left: 24px;
font-family: var(--font-mono);
font-size: 11px;
font-weight: 600;
padding: 4px 12px;
border-radius: 4px;
background: var(--accent);
color: var(--bg);
}
.slide__code-block pre {
margin: 0;
overflow-x: auto;
}
.slide__code-block code {
font-family: var(--font-mono);
font-size: clamp(14px, 1.6vw, 18px);
line-height: 1.7;
color: var(--code-text, #e6edf3);
}
```
### Quote Slide
36–48px serif with dramatic line-height. Oversized quotation mark as SVG or typographic decoration. Generous whitespace is the design.
```html
<section class="slide slide--quote">
<div class="slide__quote-mark reveal">“</div>
<blockquote class="reveal">
The best code is the code you don't have to write.
</blockquote>
<cite class="reveal">— Someone Wise</cite>
</section>
```
```css
.slide--quote {
justify-content: center;
align-items: center;
text-align: center;
padding: clamp(60px, 10vh, 120px) clamp(60px, 12vw, 200px);
}
.slide__quote-mark {
font-size: clamp(80px, 14vw, 180px);
line-height: 0.5;
opacity: 0.08;
font-family: Georgia, serif;
pointer-events: none;
margin-bottom: -20px;
}
.slide--quote blockquote {
font-size: clamp(24px, 4vw, 48px);
font-weight: 400;
line-height: 1.35;
font-style: italic;
margin: 0;
}
.slide--quote cite {
font-family: var(--font-mono);
font-size: clamp(11px, 1.4vw, 14px);
font-style: normal;
margin-top: clamp(16px, 3vh, 32px);
display: block;
letter-spacing: 1.5px;
text-transform: uppercase;
color: var(--text-dim);
}
```
### Full-Bleed Slide
Background image (surf-generated or CSS gradient) dominates the viewport. Text overlay with gradient scrim ensuring contrast. Zero slide padding.
```html
<section class="slide slide--bleed">
<div class="slide__bg" style="background-image:url('data:image/png;base64,...')"></div>
<div class="slide__scrim"></div>
<div class="slide__content">
<h2 class="slide__heading reveal">Headline Over Image</h2>
<p class="slide__subtitle reveal">Supporting text</p>
</div>
</section>
```
```css
.slide--bleed {
padding: 0;
justify-content: flex-end;
color: #ffffff;
}
.slide__bg {
position: absolute;
inset: 0;
background-size: cover;
background-position: center;
z-index: 0;
}
.slide__scrim {
position: absolute;
inset: 0;
background: linear-gradient(to top, rgba(0, 0, 0, 0.7) 0%, rgba(0, 0, 0, 0.1) 50%, transparent 100%);
z-index: 1;
}
.slide--bleed .slide__content {
position: relative;
z-index: 2;
padding: clamp(40px, 6vh, 80px) clamp(40px, 8vw, 120px);
}
/* When no generated image, use a bold CSS gradient background */
.slide__bg--gradient {
background: linear-gradient(135deg, var(--accent) 0%, color-mix(in srgb, var(--accent) 60%, var(--bg) 40%) 100%);
}
```
## Decorative SVG Elements
Inline SVG accents lift slides from functional to editorial. Use sparingly — one or two per slide, never on every slide.
### Corner Accent
```html
<!-- Top-right corner mark -->
<svg class="slide__decor slide__decor--corner" width="120" height="120" viewBox="0 0 120 120">
<line x1="120" y1="0" x2="120" y2="40" stroke="var(--accent)" stroke-width="2" opacity="0.2"/>
<line x1="80" y1="0" x2="120" y2="0" stroke="var(--accent)" stroke-width="2" opacity="0.2"/>
</svg>
```
```css
.slide__decor {
position: absolute;
pointer-events: none;
z-index: 0;
}
.slide__decor--corner {
top: 0;
right: 0;
}
```
### Section Divider Mark
```html
<!-- Horizontal rule with diamond -->
<svg class="slide__decor slide__decor--divider" width="200" height="20" viewBox="0 0 200 20">
<line x1="0" y1="10" x2="85" y2="10" stroke="var(--accent)" stroke-width="1" opacity="0.3"/>
<rect x="92" y="3" width="14" height="14" transform="rotate(45 99 10)" fill="none" stroke="var(--accent)" stroke-width="1" opacity="0.3"/>
<line x1="115" y1="10" x2="200" y2="10" stroke="var(--accent)" stroke-width="1" opacity="0.3"/>
</svg>
```
### Geometric Background Pattern
```css
/* Faint grid dots behind a slide */
.slide--with-grid::before {
content: '';
position: absolute;
inset: 0;
background-image: radial-gradient(circle, var(--border) 1px, transparent 1px);
background-size: 32px 32px;
opacity: 0.5;
pointer-events: none;
z-index: 0;
}
```
### Per-Slide Background Variation
Vary gradient direction and accent glow position across slides to create visual rhythm. Don't use a uniform background for every slide.
```css
/* Vary these per slide via inline style or nth-child */
.slide:nth-child(odd) {
background-image: radial-gradient(ellipse at 20% 80%, var(--accent-dim) 0%, transparent 50%);
}
.slide:nth-child(even) {
background-image: radial-gradient(ellipse at 80% 20%, var(--accent-dim) 0%, transparent 50%);
}
```
## Proactive Imagery
Slides should reach for visuals before defaulting to text alone. If a slide could be more compelling with an image, chart, or diagram, add one.
**surf-cli integration:** Check `which surf` at the start of every slide deck generation. If available, **generate 2–4 images minimum** for any deck over 10 slides. This is not optional when surf is available — a deck with AI-generated imagery is dramatically more compelling than one with only CSS gradients. Target these slides in priority order:
1. **Title slide** (always): background image that sets the deck's visual tone. Match the topic and palette. Use `--aspect-ratio 16:9`. Prompt example: "abstract dark geometric pattern with green accent lines, technical and minimal" for Terminal Mono preset.
2. **Full-bleed slide** (always if deck has one): immersive background for the deck's visual anchor moment. Style should match the preset — photo-realistic for Midnight Editorial, abstract/geometric for Swiss Clean, circuit-board or terminal aesthetic for Terminal Mono.
3. **Content slides with conceptual topics** (1–2 if the deck has room): illustration in the `.slide__aside` area for slides about abstract concepts. Use `--aspect-ratio 1:1`.
**Generate images before writing HTML** so they're ready to embed. The workflow:
```bash
# Check availability
which surf
# Generate (one per target slide)
surf gemini "descriptive prompt matching deck palette" --generate-image /tmp/ve-slide-title.png --aspect-ratio 16:9
# Base64 encode for self-containment (macOS)
TITLE_IMG=$(base64 -i /tmp/ve-slide-title.png)
# Linux: TITLE_IMG=$(base64 -w 0 /tmp/ve-slide-title.png)
# Embed in the slide
# <div class="slide__bg" style="background-image:url('data:image/png;base64,${TITLE_IMG}')"></div>
# Clean up
rm /tmp/ve-slide-title.png
```
**Prompt craft for slides:** Be specific about style, dominant colors, and mood. Pull colors from the preset's CSS variables. Examples:
- Terminal Mono: "dark abstract circuit board pattern, green (#50fa7b) traces on near-black (#0a0e14), minimal, technical"
- Midnight Editorial: "deep navy abstract composition, warm gold accent light, cinematic depth of field, premium editorial feel"
- Warm Signal: "warm cream textured paper with terracotta geometric accents, confident modern design"
**When surf fails or isn't available:** Degrade gracefully to CSS gradients and SVG decorations. Use the `.slide__bg--gradient` pattern with bold `linear-gradient` or `radial-gradient` backgrounds. The deck should stand on its own visually without generated images — they enhance, they don't carry. Note the fallback in an HTML comment (`<!-- surf unavailable, using CSS gradient fallback -->`) so future edits know to retry.
**Inline data visualizations:** Proactively add SVG sparklines next to numbers, mini-charts on dashboard slides, and small Mermaid diagrams on split slides even when not explicitly requested. A number with a sparkline next to it tells a better story than a number alone.
**When to skip images:** If surf isn't available, degrade gracefully — use CSS gradients and SVG decorations instead. Never error on missing surf. Pure structural or data-heavy decks (code reviews, table comparisons) may not need generated images.
## Compositional Variety
Consecutive slides must vary their spatial approach. Three centered slides in a row means push one off-axis.
**Composition patterns to alternate between:**
- Centered (title slides, quotes)
- Left-heavy: content on the left 60%, breathing room on the right
- Right-heavy: content on the right 60%, visual or whitespace on the left
- Edge-aligned: content pushed to bottom or top, large empty space opposite
- Split: two distinct panels filling the viewport
- Full-bleed: background dominates, minimal overlaid text
The agent should plan the slide sequence considering layout rhythm, not just content order. When outlining a deck, assign a composition to each slide before writing HTML.
## Presentation Readability
Slides get projected, screen-shared, viewed at distance. Design accordingly:
- **Minimum body text: 16px.** Nothing smaller except labels and captions.
- **One focal point per slide.** Not three competing elements.
- **Higher contrast than pages.** Dimmed text (`--text-dim`) should still be easily readable at distance — test against the background.
- **Nav chrome opacity.** Dots and progress bar must be visible on any slide background (light or dark) without being distracting. Use the backdrop blur or text-shadow approach from the Nav Chrome section.
- **Simpler Mermaid diagrams.** Max 8–10 nodes, 18px+ labels, 2px+ edges. The diagram should be readable without zoom at presentation distance. Zoom controls remain available for detail inspection.
## Content Density Limits
Each slide must fit in exactly 100dvh. If content exceeds these limits, the agent splits across multiple slides — never scrolls within a slide.
| Slide type | Max content |
|-----------|-------------|
| Title | 1 heading + 1 subtitle |
| Section Divider | 1 number + 1 heading + optional subhead |
| Content | 1 heading + 5–6 bullets (max 2 lines each) |
| Split | 1 heading + 2 panels, each follows its inner type's limits |
| Diagram | 1 heading + 1 Mermaid diagram (max 8–10 nodes) |
| Dashboard | 1 heading + 6 KPI cards. Hero values ≤6 chars (numbers, %, short labels). Longer strings belong in the label row. |
| Table | 1 heading + 8 rows; overflow paginates to next slide |
| Code | 1 heading + 10 lines of code |
| Quote | 1 short quote (~25 words / ~150 chars max) + 1 attribution. Longer quotes are content slides, not quote slides. |
| Full-Bleed | 1 heading + 1 subtitle over background |
## Responsive Height Breakpoints
Height-based scaling is more critical for slides than width. Each breakpoint progressively reduces padding, font sizes, and hides decorative elements.
```css
/* Compact viewports */
@media (max-height: 700px) {
.slide {
padding: clamp(24px, 4vh, 40px) clamp(32px, 6vw, 80px);
}
.slide__display { font-size: clamp(36px, 8vw, 72px); }
.slide--divider .slide__number { font-size: clamp(80px, 16vw, 160px); }
}
/* Small tablets / landscape phones */
@media (max-height: 600px) {
.slide__decor { display: none; } /* hide decorative SVGs */
.slide--quote { padding: clamp(32px, 6vh, 60px) clamp(40px, 8vw, 100px); }
.slide__quote-mark { display: none; }
}
/* Aggressive: landscape phones */
@media (max-height: 500px) {
.slide {
padding: clamp(16px, 3vh, 24px) clamp(24px, 5vw, 48px);
}
.deck-dots { display: none; } /* dots clutter tiny viewports */
.slide__display { font-size: clamp(28px, 7vw, 48px); }
}
/* Width breakpoint for grids */
@media (max-width: 768px) {
.slide--content .slide__inner { grid-template-columns: 1fr; }
.slide--content .slide__aside { display: none; }
.slide--split .slide__panels { grid-template-columns: 1fr; }
.slide--dashboard .slide__kpis { grid-template-columns: repeat(2, 1fr); }
}
```
## Curated Presets
Starting points the agent can riff on. Each defines a font pairing, palette, and background treatment. The agent adapts these to the content — different decks with the same preset should still feel distinct.
### Midnight Editorial
Deep navy, serif display, warm gold accents. Cinematic, premium. Dark-first.
```css
:root {
--font-body: 'Instrument Serif', Georgia, serif;
--font-mono: 'JetBrains Mono', 'SF Mono', monospace;
--bg: #0f1729;
--surface: #162040;
--surface2: #1d2b52;
--surface-elevated: #243362;
--border: rgba(200, 180, 140, 0.08);
--border-bright: rgba(200, 180, 140, 0.16);
--text: #e8e4d8;
--text-dim: #9a9484;
--accent: #d4a73a;
--accent-dim: rgba(212, 167, 58, 0.1);
--code-bg: #0a0f1e;
--code-text: #d4d0c4;
}
@media (prefers-color-scheme: light) {
:root {
--bg: #faf8f2;
--surface: #ffffff;
--surface2: #f5f0e6;
--surface-elevated: #fffdf5;
--border: rgba(30, 30, 50, 0.08);
--border-bright: rgba(30, 30, 50, 0.16);
--text: #1a1814;
--text-dim: #7a7468;
--accent: #b8860b;
--accent-dim: rgba(184, 134, 11, 0.08);
--code-bg: #2a2520;
--code-text: #e8e4d8;
}
}
```
Background: radial gold glow at top center. Decorative corner marks in gold. Title slides use dramatic serif at max scale.
### Warm Signal
Cream paper, bold sans, terracotta/coral accents. Confident and modern. Light-first.
```css
:root {
--font-body: 'Plus Jakarta Sans', system-ui, sans-serif;
--font-mono: 'Azeret Mono', 'SF Mono', monospace;
--bg: #faf6f0;
--surface: #ffffff;
--surface2: #f5ece0;
--surface-elevated: #fffdf5;
--border: rgba(60, 40, 20, 0.08);
--border-bright: rgba(60, 40, 20, 0.16);
--text: #2c2a25;
--text-dim: #7c756a;
--accent: #c2410c;
--accent-dim: rgba(194, 65, 12, 0.08);
--code-bg: #2c2520;
--code-text: #f5ece0;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #1c1916;
--surface: #262220;
--surface2: #302b28;
--surface-elevated: #3a3430;
--border: rgba(200, 180, 160, 0.08);
--border-bright: rgba(200, 180, 160, 0.16);
--text: #f0e8dc;
--text-dim: #a09888;
--accent: #e85d2a;
--accent-dim: rgba(232, 93, 42, 0.1);
--code-bg: #141210;
--code-text: #f0e8dc;
}
}
```
Background: warm radial glow at bottom left. Terracotta accent borders on cards. Section divider numbers in ultra-light coral.
### Terminal Mono
Dark, monospace everything, green/cyan accents, faint grid. Developer-native. Dark-first.
```css
:root {
--font-body: 'Geist Mono', 'SF Mono', Consolas, monospace;
--font-mono: 'Geist Mono', 'SF Mono', Consolas, monospace;
--bg: #0a0e14;
--surface: #12161e;
--surface2: #1a1f2a;
--surface-elevated: #222836;
--border: rgba(80, 250, 123, 0.06);
--border-bright: rgba(80, 250, 123, 0.12);
--text: #c8d6e5;
--text-dim: #5a6a7a;
--accent: #50fa7b;
--accent-dim: rgba(80, 250, 123, 0.08);
--code-bg: #060a10;
--code-text: #c8d6e5;
}
@media (prefers-color-scheme: light) {
:root {
--bg: #f4f6f8;
--surface: #ffffff;
--surface2: #eaecf0;
--surface-elevated: #f8f9fa;
--border: rgba(0, 80, 40, 0.08);
--border-bright: rgba(0, 80, 40, 0.16);
--text: #1a2332;
--text-dim: #5a6a7a;
--accent: #0d7a3e;
--accent-dim: rgba(13, 122, 62, 0.08);
--code-bg: #1a2332;
--code-text: #c8d6e5;
}
}
```
Background: faint dot grid. Everything in mono. Title slides use large weight-400 mono instead of bold display. Code slides feel native.
### Swiss Clean
White, geometric sans, single bold accent, visible grid. Minimal and precise. Light-first.
```css
:root {
--font-body: 'DM Sans', system-ui, sans-serif;
--font-mono: 'Fira Code', 'SF Mono', monospace;
--bg: #ffffff;
--surface: #f8f8f8;
--surface2: #f0f0f0;
--surface-elevated: #ffffff;
--border: rgba(0, 0, 0, 0.08);
--border-bright: rgba(0, 0, 0, 0.16);
--text: #111111;
--text-dim: #666666;
--accent: #0055ff;
--accent-dim: rgba(0, 85, 255, 0.06);
--code-bg: #18181b;
--code-text: #e4e4e7;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #111111;
--surface: #1a1a1a;
--surface2: #222222;
--surface-elevated: #2a2a2a;
--border: rgba(255, 255, 255, 0.08);
--border-bright: rgba(255, 255, 255, 0.16);
--text: #f0f0f0;
--text-dim: #888888;
--accent: #3b82f6;
--accent-dim: rgba(59, 130, 246, 0.08);
--code-bg: #0a0a0a;
--code-text: #e4e4e7;
}
}
```
Background: clean white or near-black, no gradients. Visible grid lines (the `--with-grid` pattern). Tight geometric layouts. Single accent color used sparingly for emphasis. Data-heavy and analytical content shines here.
#!/bin/bash
# Share Visual Explainer HTML via Vercel
# Usage: ./share.sh <html-file>
# Returns: Live URL instantly (no auth required)
set -e
RED='\033[0;31m'
GREEN='\033[0;32m'
CYAN='\033[0;36m'
NC='\033[0m'
HTML_FILE="${1}"
if [ -z "$HTML_FILE" ]; then
echo -e "${RED}Error: Please provide an HTML file to share${NC}" >&2
echo "Usage: $0 <html-file>" >&2
exit 1
fi
if [ ! -f "$HTML_FILE" ]; then
echo -e "${RED}Error: File not found: $HTML_FILE${NC}" >&2
exit 1
fi
# Find vercel-deploy skill
VERCEL_SCRIPT=""
for dir in ~/.pi/agent/skills/vercel-deploy/scripts /mnt/skills/user/vercel-deploy/scripts; do
if [ -f "$dir/deploy.sh" ]; then
VERCEL_SCRIPT="$dir/deploy.sh"
break
fi
done
if [ -z "$VERCEL_SCRIPT" ]; then
echo -e "${RED}Error: vercel-deploy skill not found${NC}" >&2
echo "Install it with: pi install npm:vercel-deploy" >&2
exit 1
fi
# Create temp directory with index.html
TEMP_DIR=$(mktemp -d)
trap 'rm -rf "$TEMP_DIR"' EXIT
# Copy file as index.html (Vercel serves index.html at root)
cp "$HTML_FILE" "$TEMP_DIR/index.html"
echo -e "${CYAN}Sharing $(basename "$HTML_FILE")...${NC}" >&2
# Deploy via vercel-deploy skill
# Temporarily disable errexit to capture deployment errors
set +e
RESULT=$(bash "$VERCEL_SCRIPT" "$TEMP_DIR" 2>&1)
DEPLOY_EXIT=$?
set -e
if [ $DEPLOY_EXIT -ne 0 ]; then
echo -e "${RED}Error: Deployment failed${NC}" >&2
echo "$RESULT" >&2
exit 1
fi
# Extract preview URL
PREVIEW_URL=$(echo "$RESULT" | grep -oE 'https://[^"]+\.vercel\.app' | head -1)
CLAIM_URL=$(echo "$RESULT" | grep -oE 'https://vercel\.com/claim-deployment[^"]+' | head -1)
if [ -z "$PREVIEW_URL" ]; then
echo -e "${RED}Error: Deployment failed${NC}" >&2
echo "$RESULT" >&2
exit 1
fi
echo "" >&2
echo -e "${GREEN}✓ Shared successfully!${NC}" >&2
echo "" >&2
echo -e "${GREEN}Live URL: ${PREVIEW_URL}${NC}" >&2
echo -e "${CYAN}Claim URL: ${CLAIM_URL}${NC}" >&2
echo "" >&2
# Output JSON for programmatic use (extract from vercel-deploy output)
echo "$RESULT" | grep -E '^\{' | head -1
Version History
v1.2.0
Synced from GitHub
2 weeks ago
v1.1.0
Synced from GitHub
2 weeks ago
v1.0.0
Imported from GitHub
2 weeks ago