Visual Doc

Visual Doc

Turn a spec/plan into a single self-contained, hand-drawn-styled HTML document by authoring a typed block array and rendering it. Unlike the recap (which is automatic), you compose the blocks — so ground every reference in the real repo.

Tool location (resolved through the installer's ~/.claude/visual-skills symlink — re-run npm run skills:install if the repo moves):

VISUAL_SKILLS_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/visual-skills"

Required language guide. Before writing user-facing text, read $VISUAL_SKILLS_DIR/skills/shared/plain-language.md. Apply it to every authored field and live reply.

Steps

1. Read the source spec/plan (the file the user names, or the plan already in context).

2. Read the authoritative schema: $VISUAL_SKILLS_DIR/src/blocks.ts. It defines the Block union — treat it as the source of truth for field names and shapes.

3. Ground it in the real repo: use real file paths and real identifiers from the target codebase (e.g. model names, route/procedure names, exported symbols). Do not invent identifiers.

4. Author a Block[] JSON array using the mapping below.

5. Render it from the tool directory:

   cd "$VISUAL_SKILLS_DIR"
   npx tsx bin/doc.ts --blocks <ABSOLUTE_BLOCKS_JSON> --title "<Title>" \
     --source "<source path or label>" --out <ABSOLUTE_OUT_DIR>
   

   --out is a directory (e.g. <repo>/.visual/docs/<label>, absolute path); the HTML (doc.html) and any .excalidraw sidecars are written together inside it. Diagrams render as static D2 by default and stay that way unless you opt in: pass --excalidraw to promote editable-eligible diagrams to .excalidraw scenes (requires the npm run setup:excalidraw toolchain). Without the flag — or with --no-excalidraw — you get the static D2 floor.

6. Open it: open <ABSOLUTE_OUT_DIR>/doc.html (macOS), else report the path.

Content -> block mapping

For diagram selection (which structural / boundary / data-flow / behavioral diagram to use) and compile-tested recipes, consult the shared catalog: $VISUAL_SKILLS_DIR/skills/shared/diagrams.md.

Color diagrams with the catalog's semantic palette (the "Color vocabulary" section) — mark the changed/subject node and tag actors / external systems / datastores by role.

Primary blocks you author for a doc:

• narrative / sections -> prose (Markdown; GitHub-flavored). A fenced mermaid flowchart inside prose is auto-promoted to a diagram (and becomes editable if the Excalidraw upgrade is installed).

  { "type": "prose", "id": "overview", "markdown": "## Overview\n\nWhat & why..." }
  

• architecture / flow -> diagram — d2 is required (the rendering floor); add mermaid for the editable upgrade on flowchart/architecture kinds. Quote any d2 key/value containing a dot or space.

  { "type": "diagram", "id": "flow", "title": "Request flow", "kind": "flowchart",
    "d2": "direction: down\n\"client\" -> \"api\" -> \"db\"",
    "mermaid": "graph TD\nclient-->api-->db" }
  

• affected / new files -> file-tree — status is one of A/M/D/R.

  { "type": "file-tree", "id": "files", "title": "Files", "files": [
    { "path": "src/server/routers/league.ts", "status": "M", "added": 20, "deleted": 4 } ] }
  

• key code to explain -> annotated-code — per-line notes; use for the 2-3 most important snippets, not everything. line is 1-based.

  { "type": "annotated-code", "id": "capture", "title": "captureOrder", "lang": "ts",
    "code": "const order = await paypal.capture(id);\nreturn order;",
    "annotations": [ { "line": 1, "note": "server-side capture" } ] }
  

• open decisions -> questions

  { "type": "questions", "id": "open", "title": "Open questions", "questions": [
    { "question": "Refund window?", "recommendedDefault": "30 days" } ] }
  

• grouping -> group — a titled, collapsible set of related blocks; add an optional description (markdown) summarizing what the group covers. Shape: { "type":"group", "id":"…", "title":"…", "blocks":[ … ] } (one level deep). Used mainly by recaps to order diffs into a narrative; available for any doc too.

• multiple views of one thing -> tabs — a CSS-only tab switcher (no JS) presenting complementary diagrams as switchable panels. Each tab holds ONE block, one level deep (a tab may not contain a group or another tabs).

  { "type": "tabs", "id": "views", "title": "Two views", "tabs": [
    { "label": "Flow", "block": { "type": "diagram", "id": "v-flow", "title": "Flow", "kind": "flowchart", "d2": "a -> b" } },
    { "label": "Seq",  "block": { "type": "diagram", "id": "v-seq", "title": "Seq", "kind": "sequence", "d2": "shape: sequence_diagram\na -> b: hi" } } ] }
  

• lead summary -> overview — a scannable callout placed first: a one-line headline, short points (each href linking to a section by #id), and an optional lead diagram (DiagramBlock or tabs) rendered before the points. Author it for larger docs.

  { "type": "overview", "id": "overview", "headline": "Add PayPal capture",
    "points": [ { "text": "new `capture` [route](#flow)" } ],
    "diagram": { "type": "diagram", "id": "ov-flow", "title": "Flow", "kind": "flowchart", "d2": "a -> b" } }
  

• worked instance -> example — a real input walked through stages to its output (source + lesson required; static rail by default, "reveal"/"step" for volume, variant:"contrast" for old-vs-new). See skills/shared/spec-components.md for the full recipe.

  { "type": "example", "id": "ex-capture", "title": "Capturing an authorized order",
    "source": "test/fixtures/orders/authorized.json",
    "stages": [
      { "label": "Input", "kind": "input", "body": "…" },
      { "label": "Output", "kind": "output", "body": "…" } ],
    "lesson": "Capture is idempotent — replaying it twice charges once." }
  

When to add an example: any transformation or algorithm the doc explains gets one worked instance — don't just describe the mechanism in prose, show one real case going through it.

Other block types in the Block union — schema, api, diff — are normally produced automatically by the visual-recap flow from a real git diff, not hand-authored. Reach for visual-recap when the subject is a code change rather than a plan.

Notes

• Block ids must be unique across the document.
• Keep d2 valid: quote keys/values with dots (e.g. "league.captureOrder"). If d2 fails to compile, that block renders a visible placeholder rather than breaking the document.
• Diagrams need d2 on PATH (brew install d2); without it they show placeholders.

Example

cd "$VISUAL_SKILLS_DIR"
npx tsx bin/doc.ts --blocks /tmp/doc-blocks.json --title "Payments migration" \
  --source docs/specs/payments.md --out /Users/me/Projects/app/.visual/docs/payments
open /Users/me/Projects/app/.visual/docs/payments/doc.html