You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+43Lines changed: 43 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,48 @@
1
1
# Changelog
2
2
3
+
## [0.4.0] - 2026-02-28
4
+
5
+
### New Prompt Template
6
+
-`/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.
7
+
8
+
### Prose Accent Patterns
9
+
Added patterns for use as accent elements within visual pages.
10
+
11
+
**`css-patterns.md`** — New "Prose Page Elements" section:
12
+
- Body text settings (font-size, line-height, max-width for comfortable reading)
13
+
- Lead paragraph patterns (larger size, drop cap variants)
14
+
- Pull quotes (border-left, centered with quotation mark)
15
+
- Section dividers (horizontal rule, ornamental)
16
+
- Article hero patterns (centered, editorial)
17
+
- Author byline pattern
18
+
- Prose-specific anti-patterns
19
+
20
+
**`libraries.md`** — New "Typography by Content Voice" section:
21
+
- Font recommendations by content type (literary, technical, bold, minimal)
22
+
- Special mention of Literata for screen reading
23
+
24
+
**`SKILL.md`** — New sections:
25
+
- "Prose Accent Elements" — when to use lead paragraphs, pull quotes, callouts
Copy file name to clipboardExpand all lines: README.md
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -59,11 +59,12 @@ If you have [surf-cli](https://github.com/nicobailon/surf-cli) installed, the sk
59
59
60
60
The agent loads the skill when you mention diagrams, architecture, flowcharts, schemas, or visualizations. It 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 and opens it in the browser. Output goes to `~/.agent/diagrams/`.
61
61
62
-
The skill ships with six prompt templates:
62
+
The skill ships with seven prompt templates:
63
63
64
64
| Command | What it does |
65
65
|---------|-------------|
66
66
|`/generate-web-diagram`| Generate an HTML diagram for any topic |
67
+
|`/generate-visual-plan`| Generate a visual implementation plan for a feature or extension |
67
68
|`/generate-slides`| Generate a magazine-quality slide deck for any topic |
Copy file name to clipboardExpand all lines: SKILL.md
+60-5Lines changed: 60 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ license: MIT
5
5
compatibility: Requires a browser to view generated HTML files. Optional surf-cli for AI image generation.
6
6
metadata:
7
7
author: nicobailon
8
-
version: "0.2.0"
8
+
version: "0.4.0"
9
9
---
10
10
11
11
# Visual Explainer
@@ -20,9 +20,15 @@ Generate self-contained HTML files for technical diagrams, visualizations, and d
20
20
21
21
Before writing HTML, commit to a direction. Don't default to "dark theme with blue accents" every time.
22
22
23
+
**Visual is always default.** Even essays, blog posts, and articles get visual treatment — extract structure into cards, diagrams, grids, tables.
24
+
25
+
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.
26
+
27
+
For prose accents, see "Prose Page Elements" in `./references/css-patterns.md`. For everything else, use the standard freeform approach with aesthetic directions below.
28
+
23
29
**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.
24
30
25
-
**What type of diagram?** Architecture, flowchart, sequence, data flow, schema/ER, state machine, mind map, data table, timeline, or dashboard. Each has distinct layout needs and rendering approaches (see Diagram Types below).
31
+
**What type of content?** Architecture, flowchart, sequence, data flow, schema/ER, state machine, mind map, data table, timeline, dashboard, or prose-first page. Each has distinct layout needs and rendering approaches (see Diagram Types below).
26
32
27
33
**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.
28
34
@@ -45,19 +51,20 @@ Vary the choice each time. If the last diagram was dark and technical, make the
45
51
46
52
### 2. Structure
47
53
48
-
**Read the reference template** before generating. Don't memorize it — read it each time to absorb the patterns.
54
+
**Read the reference material** before generating. Don't memorize it — read it each time to absorb the patterns.
49
55
- For text-heavy architecture overviews (card content matters more than topology): read `./templates/architecture.html`
50
56
- For flowcharts, sequence diagrams, ER, state machines, mind maps: read `./templates/mermaid-flowchart.html`
51
57
- For data tables, comparisons, audits, feature matrices: read `./templates/data-table.html`
52
58
- For slide deck presentations (when `--slides` flag is present or `/generate-slides` is invoked): read `./templates/slide-deck.html` and `./references/slide-patterns.md`
59
+
- 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`
53
60
54
61
**For CSS/layout patterns and SVG connectors**, read `./references/css-patterns.md`.
55
62
56
63
**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.
| Architecture (topology-focused) |**Mermaid**| Visible connections between components need automatic edge routing |
@@ -73,7 +80,9 @@ Vary the choice each time. If the last diagram was dark and technical, make the
73
80
74
81
**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.
75
82
76
-
**Mermaid zoom controls:** Always add zoom controls (+/−/reset buttons) to every `.mermaid-wrap` container. Complex diagrams render at small sizes and need zoom to be readable. Include Ctrl/Cmd+scroll zoom on the container. See the zoom controls pattern in `./references/css-patterns.md` and the reference template at `./templates/mermaid-flowchart.html`.
83
+
**Mermaid containers:** Always center Mermaid diagrams with `display: flex; justify-content: center;`. Add zoom controls (+/−/reset) to every `.mermaid-wrap` container.
84
+
85
+
**Mermaid scaling:** Complex diagrams with 10+ nodes render too small by default. Increase `fontSize` in themeVariables to 18-20px (default is 16px), or apply a CSS `transform: scale(1.3)` on the SVG. Don't let diagrams float in oversized containers with unreadable text. See `./references/css-patterns.md` "Scaling Small Diagrams".
77
86
78
87
**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`).
79
88
@@ -227,6 +236,52 @@ Vertical or horizontal timeline with a central line (CSS pseudo-element). Phase
227
236
### Dashboard / Metrics Overview
228
237
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).
229
238
239
+
### Implementation Plans
240
+
241
+
For visualizing implementation plans, extension designs, or feature specifications. The goal is **understanding the approach**, not reading the full source code.
242
+
243
+
**Don't dump full files.** Displaying entire source files inline overwhelms the page and defeats the purpose of a visual explanation. Instead:
244
+
- Show **file structure with descriptions** — list functions/exports with one-line explanations
245
+
- Show **key snippets only** — the 5-10 lines that illustrate the core logic
246
+
- Use **collapsible sections** for full code if truly needed
247
+
248
+
**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.
249
+
250
+
**Structure for implementation plans:**
251
+
1. Overview/purpose (what problem does this solve?)
252
+
2. Flow diagram (Mermaid or CSS cards)
253
+
3. File structure with descriptions (not full code)
254
+
4. Key implementation details (snippets)
255
+
5. API/interface summary
256
+
6. Usage examples
257
+
258
+
### Documentation (READMEs, Library Docs, API References)
259
+
260
+
When visualizing documentation, extract structure into visual elements:
261
+
262
+
| Content | Visual Treatment |
263
+
|---------|------------------|
264
+
| Features | Card grid (2-3 columns) |
265
+
| Install/setup steps | Numbered cards or vertical flow |
266
+
| API endpoints/commands | Table with sticky header |
267
+
| Config options | Table |
268
+
| Architecture | Mermaid diagram or CSS card layout |
269
+
| Comparisons | Side-by-side panels or table |
270
+
| Warnings/notes | Callout boxes |
271
+
272
+
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.
273
+
274
+
### Prose Accent Elements
275
+
276
+
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.
277
+
278
+
-**Lead paragraph** — larger intro text to set context before diving into cards/grids
279
+
-**Pull quote** — highlight a key insight; one per page maximum
280
+
-**Callout box** — warnings, tips, important notes
281
+
-**Section divider** — visual break between major sections
282
+
283
+
**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.
284
+
230
285
## Slide Deck Mode
231
286
232
287
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.
description: Generate a visual HTML implementation plan — detailed feature specification with state machines, code snippets, and edge cases
3
+
---
4
+
Load the visual-explainer skill, then generate a comprehensive visual implementation plan for `$@` as a self-contained HTML page.
5
+
6
+
Follow the visual-explainer skill workflow. Read the reference template, CSS patterns, and mermaid theming references before generating. Use an editorial or blueprint aesthetic, but vary fonts and palette from previous diagrams.
7
+
8
+
**Data gathering phase** — understand the context before designing:
9
+
10
+
1.**Parse the feature request.** Extract:
11
+
- The core problem being solved
12
+
- Desired user-facing behavior
13
+
- Any constraints or requirements mentioned
14
+
- Scope boundaries (what's explicitly out of scope)
15
+
16
+
2.**Read the relevant codebase.** Identify:
17
+
- Files that will need modification
18
+
- Existing patterns to follow (code style, architecture, naming conventions)
19
+
- Related functionality that the feature should integrate with
20
+
- Types, interfaces, and APIs the feature must conform to
21
+
22
+
3.**Understand the extension points.** Look for:
23
+
- Hook points, event systems, or plugin architectures
24
+
- Configuration options or flags
25
+
- Public APIs that might need extension
26
+
- Test patterns used in the codebase
27
+
28
+
4.**Check for prior art.** Search for:
29
+
- Similar features already implemented
30
+
- Related issues or discussions
31
+
- Existing code that can be reused or extended
32
+
33
+
**Design phase** — work through the implementation before writing HTML:
34
+
35
+
1.**State design.** What new state variables are needed? What existing state is affected? Draw the state machine if behavior has multiple modes.
36
+
37
+
2.**API design.** What commands, functions, or endpoints are added? What are the signatures? What are the error cases?
38
+
39
+
3.**Integration design.** How does this feature interact with existing functionality? What hooks or events are involved?
40
+
41
+
4.**Edge cases.** Walk through unusual scenarios: concurrent operations, error conditions, boundary values, user mistakes.
42
+
43
+
**Verification checkpoint** — before generating HTML, produce a structured fact sheet:
44
+
- Every state variable (new and modified) with its type and purpose
45
+
- Every function/command/API with its signature
46
+
- Every file that needs modification with the specific changes
47
+
- Every edge case with expected behavior
48
+
- Every assumption about the codebase that the plan relies on
49
+
Verify each against the code. If something cannot be verified, mark it as uncertain. This fact sheet is your source of truth during HTML generation.
50
+
51
+
**Diagram structure** — the page should include:
52
+
53
+
1.**Header** — feature name, one-line description, scope summary. *Visual treatment: use a distinctive header with monospace label ("Feature Plan", "Implementation Spec", etc.), large italic title, and muted subtitle. Set the tone for the page.*
54
+
55
+
2.**The Problem** — side-by-side comparison panels showing current behavior vs. desired behavior. Use concrete examples, not abstract descriptions. Show what the user experiences or what the code does, step by step. *Visual treatment: two-column grid with rose-tinted "Before" header and sage-tinted "After" header. Numbered flow steps with arrows between them.*
56
+
57
+
3.**State Machine** — Mermaid flowchart or stateDiagram showing the states and transitions. Label edges with the triggers (commands, events, conditions). *Wrap in `.mermaid-wrap` with zoom controls. Use `flowchart LR` instead of `stateDiagram-v2` if labels need special characters like colons or parentheses. Add explanatory caption below the diagram.*
58
+
59
+
4.**State Variables** — card grid showing new state and existing state (if modified). Use code blocks with proper `white-space: pre-wrap`. *Visual treatment: two cards side-by-side, elevated depth, monospace labels.*
60
+
61
+
5.**Modified Functions** — for each function that needs changes, show:
62
+
- Function name and file path
63
+
- Key code snippet (not full implementation — 10-20 lines showing the pattern)
64
+
- Explanation of what changed and why
65
+
*Visual treatment: file path as monospace dim text above code block, code in recessed card with accent-dim background.*
66
+
67
+
6.**Commands / API** — table with command/function name, parameters, and behavior description. Use `<code>` for technical names. *Visual treatment: bordered table with sticky header, alternating row backgrounds.*
68
+
69
+
7.**Edge Cases** — table listing scenarios and expected behaviors. Be thorough — include error conditions, concurrent operations, boundary values. *Visual treatment: same table style as Commands section.*
70
+
71
+
8.**Test Requirements** — table or card grid showing test categories and specific tests to add. Group by: unit tests, integration tests, edge case tests. *Visual treatment: compact table with file references.*
72
+
73
+
9.**File References** — table mapping files to the changes needed. Include file paths and brief descriptions. *Visual treatment: compact reference table, can use `<details>` if many files.*
- Sections 7-10 are reference material (flat or recessed depth, compact layout)
85
+
86
+
**Typography and color:**
87
+
- Pick a distinctive font pairing (not Inter/Roboto)
88
+
- Use semantic accent colors: gold for primary accents, sage for "after"/success states, rose for "before"/warning states
89
+
- Both light and dark themes must work
90
+
91
+
**Optional hero image** — if `surf` CLI is available (`which surf`), consider generating a conceptual illustration that captures the feature's essence. Use for abstract concepts that benefit from visual metaphor. Skip for purely structural changes. Embed as base64 data URI using the `.hero-img-wrap` pattern from css-patterns.md.
92
+
93
+
**Code block requirements:**
94
+
- Always use `white-space: pre-wrap` and `word-break: break-word`
95
+
- Include file path headers where relevant
96
+
- Use syntax-appropriate highlighting via CSS classes if desired
97
+
- Keep snippets focused — show the pattern, not the full implementation
98
+
99
+
**Overflow prevention:**
100
+
- Apply `min-width: 0` on all grid/flex children
101
+
- Use `overflow-wrap: break-word` on all text containers
102
+
- Never use `display: flex` on `<li>` for markers — use absolute positioning
103
+
- Test tables with wide content don't overflow their container
104
+
105
+
Write to `~/.agent/diagrams/` with a descriptive filename (e.g., `feature-name-plan.html`). Open the result in the browser. Tell the user the file path.
0 commit comments