Visualize

Generate high-quality visualizations using Claude's native artifact capabilities as primary output, with Mermaid and file-based alternatives for portability. The skill auto-detects visualization type from natural language and applies a design system for consistent, readable output.

Output follows ${CLAUDE_SKILL_DIR}/template.md and saves to ~/Tandem/creative/visualizations/.

For design tokens, load ${CLAUDE_SKILL_DIR}/references/design-system.md once per conversation when generating native or file-based output. For quality guardrails, also load ${CLAUDE_SKILL_DIR}/references/design-anti-patterns.md alongside design-system.md -- it describes patterns to AVOID. For diagram types, load ${CLAUDE_SKILL_DIR}/references/diagrams.md when needed. For data charts, load ${CLAUDE_SKILL_DIR}/references/charts.md when needed.

---

Language

See METHODOLOGY.md language mirror rule. Reply in the user's language.

---

Proactive Offer

When activated through normal conversation (not a direct visualization request), detect if the current discussion contains complex information that would benefit from a visual:

Detection signals:

• User describing a multi-step process or workflow (3+ steps)
• User comparing 3+ items or options
• User explaining a system with interconnected components
• User presenting hierarchical or organizational information
• User sharing data with 4+ data points that could be charted

When detected, offer via AskUserQuestion:

AskUserQuestion: "This might be clearer as a [type]. Want me to visualize it?"
Options: ["Yes, create a [type]", "No thanks"]

Rules:

• Offer ONCE per topic — do not repeat if declined
• Do NOT offer for simple lists, single comparisons, or straightforward explanations
• Do NOT interrupt the user's flow — wait for a natural pause
• [type] is auto-detected from the content using verb-based routing (Step 2)
• If user accepts, proceed to Step 1 (Load Preferences) with the detected content

---

Step 1: Load Preferences

Read ~/Tandem/creative/MEMORY.md if it exists. Extract visualization preferences:

• Preferred color scheme (dark/light)
• Color palette preference
• Detail level (minimal/standard/detailed)
• Default output mode (native/mermaid/file)

If preferences found, briefly show them: "Using your preferred [dark mode, blue palette, standard detail]. Override with 'use light mode' or similar."

If no preferences found, use sensible defaults: light mode, teal/purple/coral palette, standard detail, native output.

---

Step 2: Verb-Based Routing

Auto-detect visualization type from the user's natural language. Do NOT ask "what type of diagram?" unless genuinely ambiguous.

User Phrase Pattern	Visualization Type	Reference to Load
"how does X work", "explain X" (spatial)	Illustrative diagram	diagrams.md
"walk me through", "steps to", "process for"	Flowchart	diagrams.md
"compare X vs Y", "X versus Y", "differences between"	Comparison layout	diagrams.md
"show me the data", "chart this", "graph of"	Data chart (Chart.js)	charts.md
"map out", "mind map", "brainstorm map"	Mind map	diagrams.md
"timeline of", "history of", "sequence of events"	Timeline	diagrams.md
"org chart", "hierarchy", "reporting structure"	Org chart / hierarchy	diagrams.md
"architecture of", "system design", "components of"	Architecture / structural	diagrams.md
"ER diagram", "database schema"	ER diagram (Mermaid preferred)	diagrams.md
Ambiguous ("visualize this")	Infer from content; default to illustrative	diagrams.md

Load the appropriate reference file from ${CLAUDE_SKILL_DIR}/references/ based on the detected type.

---

Step 3: Output Mode Selection

Determine the best output mode. Do NOT ask unless the user has a stored preference or the situation is genuinely ambiguous.

Mode priority:

1. Native artifact (primary): Generate inline artifacts using Claude's native visualization -- React components, SVG, HTML/CSS/JS, interactive charts. Use this by default.

2. Mermaid (alternative): Auto-suggest when:

   • User explicitly asks for Mermaid
   • Output needs to work in GitHub, Notion, Obsidian
   • Diagram type is ER, sequence, or gantt (Mermaid excels here)
   • Complex flowchart with many branches (Mermaid auto-layout handles better)

3. File-based HTML/SVG (fallback): Use when:

   • User asks for a file to open in browser
   • Visualization is too complex for inline rendering
   • Chart.js interactive charts (self-contained HTML with CDN-loaded Chart.js)

If user's stored preference overrides default, use their preference.

---

Step 4: Load Design System

Load ${CLAUDE_SKILL_DIR}/references/design-system.md and ${CLAUDE_SKILL_DIR}/references/design-anti-patterns.md once per conversation (not per request). Apply design system tokens to all outputs and check against anti-patterns before finalizing:

• Color palette from design system (or user's preferred palette)
• Typography: 14px labels, 12px subtitles
• SVG viewBox width: 680px
• Max 8-10 nodes per diagram (route to Mermaid if more needed)
• Spacing: 60px between elements, 24px internal padding
• Anti-patterns: check output against design-anti-patterns.md before presenting

---

Step 5: Generate Visualization

Generate the visualization using the selected type and output mode.

For native artifacts:

• Apply design system tokens (colors, fonts, spacing)
• SVG: use 680px viewBox, pre-calculated positions, L-bend arrow routing
• HTML/CSS/JS: self-contained, use CSS variables for theme adaptation
• React components: functional components with inline styles
• Charts: Chart.js with responsive=true, theme-aware colors

For Mermaid:

• Generate valid Mermaid syntax in a fenced code block
• Include theme directive matching user's color scheme
• Types: flowchart, sequence, mindmap, timeline, erDiagram, classDiagram, gantt

For file-based:

• Write self-contained HTML with CDN-loaded libraries (Chart.js 4.4.1 via cdn.jsdelivr.net, Mermaid.js 10.x)
• Include <noscript> fallback with text-based data table
• Comment in file: <!-- Requires internet connection for CDN libraries -->

Complexity guard: Before generating raw SVG, assess complexity. If >8-10 nodes, recommend Mermaid: "This has [N] elements. Mermaid's auto-layout engine will handle this more reliably. Want me to use Mermaid instead?" Only ask if native was the selected mode and complexity is genuinely high.

---

Step 6: Present and Offer Save

Present the visualization. Then offer to save:

AskUserQuestion: "What would you like to do with this visualization?"
Options: ["Save as-is", "Refine it", "Try a different style", "Try Mermaid version", "Done -- don't save"]

If "Refine it": ask what to change, regenerate, re-present. If "Try Mermaid version": regenerate same content as Mermaid, re-present.

After Save Confirmation

1. Save visualization file:

• Native artifacts: save as viz-YYYY-MM-DD-slug.md with artifact code in fenced block
• Mermaid: save as viz-YYYY-MM-DD-slug.md with mermaid code block
• File-based HTML: save as viz-YYYY-MM-DD-slug.html
• File-based SVG: save as viz-YYYY-MM-DD-slug.svg
• Write to ~/Tandem/creative/visualizations/. Create directory if needed.
• Slug: lowercase title, spaces to hyphens, strip special characters, max 40 chars.

2. Log to stats.json:

Read ~/Tandem/stats.json. If it does not exist, create it as []. Append:

{
  "type": "visualize",
  "action": "created",
  "count": 1,
  "timeSavedMinutes": 10,
  "description": "Viz: [slug] ([type] via [mode])",
  "timestamp": "<current ISO 8601 UTC>"
}

3. Run /sync:

Follow the /sync workflow from tandem-skills/core/sync/SKILL.md. If /sync fails, continue.

4. Confirm to user:

Report the saved file path.

---

Analogy-First Mode

When the user asks to explain a concept visually (detected phrases: "explain X visually", "make an infographic about", "help me understand X"), activate analogy-first mode.

The rule: Find the killer analogy FIRST, then build the visual around it.

Step A: Find the Analogy

Search these categories for the best fit:

Category	Example Analogies	Best For
Everyday Life	Kitchen, closet, mailbox, filing cabinet	Organization, storage, interfaces
Jobs and Roles	Receptionist, translator, bouncer, librarian	Routing, filtering, managing
Construction	Blueprint, foundation, scaffolding, plumbing	Architecture, infrastructure
Cooking	Recipe, ingredients, oven, mise en place	Processes, combining inputs
Sports	Playbook, coach, relay race, referee	Strategy, teamwork, handoffs
Nature	Root system, beehive, food chain, ecosystem	Networks, hierarchies, cycles

Analogy criteria:

• Clicks in under 3 seconds
• A 10-year-old would get it
• Maps to 3+ parts of the concept
• Fresh — avoid cliches ("it's like a brain" for AI)

Step B: Map the Analogy

Real Concept	Analogy Equivalent	Visual Element	Why It Works
[Part 1]	[Analogy part]	[What to draw]	[Connection]
[Part 2]	[Analogy part]	[What to draw]	[Connection]
[Part 3]	[Analogy part]	[What to draw]	[Connection]

Every part of the concept MUST map to something in the analogy. If a piece doesn't map cleanly, the analogy is wrong — pick a better one.

Step C: Build the Visual

Generate the visualization using the mapped analogy. The analogy elements become the visual elements. Apply the standard design system and component catalog.

Max 50 words of text on the entire graphic. The visual should make sense even without reading the text.

---

Visual Component Catalog

Standard components for consistent, high-quality visual output. Use these across all visualization types (native, Mermaid, file-based).

Component	When to Use	Structure
Stat Cards	Key numbers, KPIs	Horizontal row: large number + label + optional trend arrow
Section Cards	Feature lists, grouped info	Grid of cards: icon/emoji + title + description
Comparison Grid	Side-by-side analysis	2-3 columns, rows with checkmarks or values
Flow Steps	Sequential processes	Numbered circles connected by lines + title + description
Status Badges	Tags, categories, states	Colored pill badges (green/yellow/red/blue)
Callout Boxes	Important notes, warnings	Accent left border, icon, highlighted background
Progress Bars	Completion, capacity, scores	Horizontal bar with fill percentage and label
Tables	Structured data, specs	Striped rows, sticky header, responsive scroll
Timelines	Chronological events	Vertical line with dots, alternating left/right cards
Quote Blocks	Testimonials, key statements	Large quotation mark, italic text, attribution
Icon Grids	Feature overviews, tool lists	2-3 column grid: emoji + title + one-line description
Card Grid	Features, benefits, categories	2-4 cards with icon, title, one-line description

Rules:

• Every section needs a visual component — no walls of text
• Max 50 words before a visual element
• Consistent spacing using design system tokens
• Accessible (WCAG AA contrast minimum)

---

Workflow Node Color Coding

When generating workflow diagrams, system maps, or process flows, use this standard color scheme for node types:

Node Type	Background	Border	Icon Style
Trigger	#1e3a5f	#3B82F6 (blue)	Lightning bolt, clock, webhook
Processing	#1a3d2e	#10B981 (green)	Gear, wand, filter
Tool / Service	#3d2e1a	#F59E0B (amber)	Tool logo or wrench
Output	#3d1a1a	#EF4444 (red)	Check, send, export
Data Store	#1a1a2e	#6366F1 (indigo)	Database, folder, file
Decision	#2e1a3d	#A855F7 (purple)	Question mark, fork

Connection lines:

• Solid lines with arrowheads
• Color matches source node border
• Optional data label on the line showing what flows
• Decision branches need labeled conditions ("Yes"/"No" or specific criteria)

Interactivity (file-based HTML output):

• Hover: node scales 1.05x, border glows, tooltip with step description
• Click: highlights node and direct connections, dims unrelated nodes
• Background click: resets all highlighting

Include a color-coded legend at the bottom of every workflow diagram: Blue = Triggers | Green = Processing | Amber = Tools | Red = Outputs | Indigo = Data Stores | Purple = Decisions

---

Anti-Patterns

• Do NOT ask "what type of diagram?" if verb routing can determine it
• Do NOT generate raw SVG with >8-10 nodes -- recommend Mermaid instead
• Do NOT fabricate data for charts -- ask user to provide data if missing
• Do NOT use the Bash tool -- all operations via allowed-tools only
• Do NOT batch multiple questions -- one AskUserQuestion at a time
• Do NOT include gradients, shadows, blur, or display:none in SVG (streaming constraints)
• Do NOT generate inline visuals that depend on Cowork iframe rendering -- file-based output is the safe fallback
• Do NOT show empty sections in output

---

Error Handling

• Ambiguous request: Infer type from content, default to illustrative diagram.
• No data for chart: Ask user to provide data. Do NOT generate with fake numbers.
• SVG rendering concern: Offer Mermaid as alternative.
• Stats.json write fails: Continue -- visualization file is primary deliverable.
• Sync fails: Continue.
• Preferences file missing: Use defaults. Do NOT error.

---

Memory

Memory is user-triggered only. After completing a visualization, offer to remember preferences:

"Want me to remember your [dark mode / blue palette / standard detail] preferences for next time?"

If user agrees, write to ~/Tandem/creative/MEMORY.md using memory-create patterns. Include:

• preferred_color_scheme: dark/light
• preferred_palette: name or hex values
• detail_level: minimal/standard/detailed
• default_output_mode: native/mermaid/file