claude-tweaks-visualize

name	claude-tweaks:visualize
description	Use when you want a themed, project-local visual diagram — architecture, flowchart, sequence, state, ER, timeline, swimlane, quadrant, nested, tree, org chart, layer stack, venn, or pyramid — generated as self-contained HTML+SVG and styled from the project's own DESIGN.md tokens. Works standalone or as a soft-hook suggestion from /journeys, /specify, and /review.

Interaction style: Present single decisions via the AskUserQuestion tool (options with one marked Recommended) instead of a plain-text numbered list. For multi-item decisions, render a batch table with recommended actions pre-filled, then capture the apply-all/override decision via one AskUserQuestion call. Never make more than one AskUserQuestion call per logical decision — resolve each before showing the next. End skills with a ## Next Actions block rendered via AskUserQuestion (context-specific options, one recommended), not a navigation menu.

Visualize — Themed Diagram Generation

Generates a self-contained HTML+SVG diagram, themed from the project's own design tokens, embeddable in project docs.

                       [ /claude-tweaks:visualize ] ← utility (no fixed lifecycle position)
                                    ↑
   Used by: /claude-tweaks:journeys (Step 3.6), /claude-tweaks:specify (Step 2.5d),
            /claude-tweaks:review (Lens 3i-diagram), ad-hoc direct invocation

When to Use

• A journey, spec, or review finding describes something a diagram would clarify — a state machine, a data model, a multi-actor flow, a decision tree, or a layered architecture.
• You want a quick diagram of an idea mid-conversation, whether or not it ends up as a committed project doc.
• You want to replace a hand-drawn or stale diagram with one that matches the project's actual current palette.

Input

$ARGUMENTS is parsed as <type> <topic>:

Type	Diagram
architecture	3+ components/services in a system layout
flowchart	Branching logic with named conditions
sequence	2+ actors exchanging messages over time
state	An entity has named states + transitions
er	Schema/entities with relations
timeline	Ordered events along a fixed axis
swimlane	A process crosses 2+ roles/departments
quadrant	Two-axis ranking
nested	Contained/grouped relationships
tree	Parent-child hierarchy, taxonomy
org-chart	Reporting structure
layers	Abstraction levels (transport → app → ui)
venn	Set overlap
pyramid	Stacked priority/maturity levels

<topic> is free text describing what to diagram. If $ARGUMENTS is empty, ask the user for both.

Flags:

• --source <caller> — set by soft-hook callers (journeys, specify, review) to select default placement (Step 3) without prompting.

Workflow

Step 1: Resolve type, topic, and generation path

Resolve <type> from Input. Look up the generation path — enhanced when the d2 binary is installed (d2 --version exits 0) and the type has a D2-native mapping; baseline otherwise (always available):

Type	Path	D2 construct
sequence	Enhanced	shape: sequence_diagram
er	Enhanced	shape: sql_table
architecture, flowchart, tree, layers, state, org-chart, nested	Enhanced	Container-based directed graph
quadrant	Enhanced (tentative — confirm against current D2 docs; fall back to baseline if unsupported)	Grid layout
timeline, swimlane, venn, pyramid	Baseline only	No native fit

Both paths continue to Step 2 (token extraction) next — the enhanced path needs tokens too, for re-theming the D2 render.

Step 2: Token extraction and theming (both paths)

Read skills/_shared/visual-html-output.md Steps 1-2. Extract tokens from DESIGN.md/DESIGN.json when present; otherwise run the fallback AskUserQuestion (once per session — see the dedupe rule in that file). Then continue to Step 3 (resolve placement) — both paths need this before proceeding, since the enhanced path needs a known destination path before it writes its versioned .d2/.svg source files.

Step 3: Resolve placement

Caller (--source)	Placement
journeys	docs/journeys/{journey-name}-{type}.html
specify	docs/plans/{spec-slug}-{type}.html
review	Ephemeral by default; ask before persisting near docs/architecture.md
(none — direct invocation)	Run visual-html-output.md Step 6's AskUserQuestion; "Save as a project doc" resolves to docs/diagrams/{slug}.html

Now branch: for the enhanced path (resolved in Step 1), read d2-enhanced-path.md in this skill's directory — it now has a resolved destination path to write to — then continue to Step 5. For the baseline path, continue to Step 4 below.

Step 4: Generate the core fragment (baseline path)

Author the <svg> content directly for the diagram type and topic, binding every color to var(--token-name) from Step 2's extracted (or neutral fallback) palette. Follow visual-html-output.md Step 3's scoping rule — every custom class prefixed with a unique per-diagram slug.

Step 5: Write wrapper outputs

Apply visual-html-output.md Step 4's adapters. Always write the standalone-file wrapper to the path from Step 3. Write the markdown-embed wrapper's content inline in this skill's own response (for the user to copy into a doc) rather than as a separate file — it's a snippet, not a standalone artifact.

Alongside the embed snippet, also surface a suggested files: frontmatter line naming the diagram's depicted source dependencies (the files under discussion when the diagram's topic was resolved in Step 1) — e.g.:

files:
  - packages/food-graph/src/resolvers/ingredient-resolver.ts

This skill doesn't own the doc that embeds the diagram, so it doesn't write this itself — the caller (typically the user, copy-pasting the embed snippet in by hand) applies it to that doc's frontmatter alongside the snippet, giving /claude-tweaks:docs-health's freshness-dependency check (_shared/criteria-docs-diataxis.md Dimension 2) something to track. Skip this output when the diagram has no clear source-file dependency (e.g. a purely conceptual diagram with no 1:1 code mapping).

Step 6: Registry update (persisted diagrams only)

If Step 3 resolved to docs/diagrams/{slug}.html (the context-free fallback path) and no REGISTRY.md row for docs/diagrams/ exists yet, add one: | docs/diagrams/ | Generated visual diagrams | — | (no Auto-detect — matches architecture.md/decisions/*.md treatment). Diagrams placed under docs/journeys/ or docs/plans/ need no new row — they ride along with that doc's existing registry entry.

Next Actions

After generating, call AskUserQuestion with question: "What's next?", header: "Next step", multiSelect: false, and:

• Option 1 — label: "Generate another diagram (Recommended if more signals matched)", description: "/claude-tweaks:visualize <type> <topic> — generate another diagram"
• Option 2 — label: "Continue the calling flow", description: "Return to wherever this was invoked from (journey commit, spec summary, review findings)"
• Option 3 (only when persisted) — label: "View the file", description: "Open {path} to see the generated diagram"

Component-Skill Contract

When $PIPELINE_RUN_DIR is set, /claude-tweaks:visualize is running inside a pipeline (invoked by /claude-tweaks:journeys, /claude-tweaks:specify, /claude-tweaks:review, or another pipeline orchestrator). In that case omit the ## Next Actions block — the parent owns the handoff.

Direct invocation may pass --source <parent-skill> as an explicit fallback when ambiguity exists (rare; $PIPELINE_RUN_DIR is the primary signal).

Anti-Patterns

Pattern	Why It Fails
Regenerating the core fragment separately per wrapper	The standalone file and markdown embed drift apart. Generate once (Step 4), wrap two ways (Step 5).
Re-asking the DESIGN.md fallback question every invocation	Annoys a user who's already decided not to use Impeccable. Dedupe per session (visual-html-output.md Step 2).
Forcing a baseline-only type through the D2 enhanced path	Timeline/swimlane/venn/pyramid have no graph-shaped representation — this fights the tool the same way theming fights Mermaid/D2's own engines.
Writing every diagram to a single central docs/diagrams/ folder regardless of caller	Co-locate with what the diagram illustrates (Step 3) — docs/diagrams/ is the fallback for context-free invocations only.

Relationship to Other Skills

Skill	Relationship
/claude-tweaks:journeys	Step 3.6 invokes this skill with --source journeys when a journey shows a multi-persona, decision-tree, or multi-actor signal.
/claude-tweaks:specify	Step 2.5d invokes this skill with --source specify for every surface (not just frontend) when the design doc describes a state machine, schema, multi-actor flow, decision tree, layered architecture, or hierarchy.
/claude-tweaks:review	Lens 3i-diagram invokes this skill with --source review as an informational finding when the diff added structural complexity with no matching diagram on disk.
/claude-tweaks:design	Not invoked directly — this skill reads DESIGN.md/DESIGN.json (written by /impeccable:impeccable document, the same files /design pre-build mode lazy-loads) but does not go through the /design wrapper, since it needs the raw token data, not a critique/audit/polish action.
/claude-tweaks:init	Step 11 offers to enable diagram suggestions (writes diagram-suggestions: enabled/disabled to CLAUDE.md — no install step, this skill is native).
/claude-tweaks:help	/help references /visualize in the workflow diagram and reference card.
skills/_shared/visual-html-output.md	Shared core this skill consumes for token extraction, wrapper adapters, MDX/Nextra compatibility, and the persist-vs-ephemeral decision.