advanced-visualization-techniques

name	Advanced Visualization Techniques
description	UI mockups, dashboards, advanced interactivity, generative art, simulations, math visualizations, and design system rules for producing rich HTML widget output.
allowed-tools	[]

Agent Visualization Skills — Volume 2: Advanced Techniques

Prerequisite: Volume 1 (SVG diagrams, basic interactive widgets, Chart.js, Mermaid). This volume covers: UI mockups, dashboards, advanced interactivity, generative art, simulations, math visualizations, and the design system that ties everything together.

---

Part 1: The Design System

Every visual you produce should feel native to the host interface — not like an embedded iframe from somewhere else. These rules apply to ALL output types.

CSS Variables (Auto Light/Dark Mode)

/* Backgrounds */
--color-background-primary    /* white in light, near-black in dark */
--color-background-secondary  /* surface cards */
--color-background-tertiary   /* page background */
--color-background-info       /* blue tint */
--color-background-danger     /* red tint */
--color-background-success    /* green tint */
--color-background-warning    /* amber tint */

/* Text */
--color-text-primary          /* main text */
--color-text-secondary        /* muted / labels */
--color-text-tertiary         /* hints / placeholders */
--color-text-info / -danger / -success / -warning

/* Borders */
--color-border-tertiary       /* default: 0.15 alpha */
--color-border-secondary      /* hover: 0.3 alpha */
--color-border-primary        /* active: 0.4 alpha */

/* Typography */
--font-sans                   /* default body font */
--font-serif                  /* editorial / blockquote only */
--font-mono                   /* code */

/* Layout */
--border-radius-md            /* 8px - most elements */
--border-radius-lg            /* 12px - cards */
--border-radius-xl            /* 16px - large containers */

Critical rule: Never hardcode colors like #333 or #fff in HTML. They break in the opposite mode. Always use CSS variables.

Typography Rules

• h1 = 22px, h2 = 18px, h3 = 16px — all font-weight: 500
• Body = 16px, weight 400, line-height: 1.7
• Only two weights: 400 (regular) and 500 (medium). Never 600 or 700.
• Sentence case everywhere. Never Title Case or ALL CAPS.
• No mid-sentence bolding. Use code style for entity/class/function names.
• No font-size below 11px anywhere.

Component Tokens

• Borders: 0.5px solid var(--color-border-tertiary)
• Cards: background: var(--color-background-primary), border: 0.5px solid var(--color-border-tertiary), border-radius: var(--border-radius-lg), padding: 1rem 1.25rem
• No gradients, drop shadows, blur, glow, or neon effects
• No emoji — use CSS shapes or SVG paths for icons
• Background of outer container is always transparent

Number Formatting

Always round displayed numbers. JavaScript float math leaks artifacts: 0.1 + 0.2 = 0.30000000000000004. Every number on screen must go through Math.round(), .toFixed(n), or Intl.NumberFormat.

---

Part 2: UI Mockups

For when the user asks you to design or prototype a UI.

When to Use

• "Design a settings page for..."
• "Mock up a dashboard"
• "What should this form look like?"
• "Show me a card layout for..."
• Prototyping before building

Presentation Rules

Contained mockups (mobile screens, modals, chat threads, single cards): Wrap in a background surface so they don't float naked:

<div style="background: var(--color-background-secondary);
            border-radius: var(--border-radius-lg);
            padding: 2rem; display: flex; justify-content: center;">
  <!-- Your mockup inside -->
</div>

Full-width mockups (dashboards, settings pages, data tables): No wrapper needed — they naturally fill the viewport.

Metric Cards (for dashboards)

<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
            gap: 12px; margin-bottom: 1.5rem;">

  <div style="background: var(--color-background-secondary);
              border-radius: var(--border-radius-md); padding: 1rem;">
    <div style="font-size: 13px; color: var(--color-text-secondary);
                margin-bottom: 4px;">Total revenue</div>
    <div style="font-size: 24px; font-weight: 500;">$142,800</div>
  </div>

  <div style="background: var(--color-background-secondary);
              border-radius: var(--border-radius-md); padding: 1rem;">
    <div style="font-size: 13px; color: var(--color-text-secondary);
                margin-bottom: 4px;">Active users</div>
    <div style="font-size: 24px; font-weight: 500;">8,421</div>
  </div>

</div>

Contact / Data Record Card

<div style="background: var(--color-background-primary);
            border-radius: var(--border-radius-lg);
            border: 0.5px solid var(--color-border-tertiary);
            padding: 1rem 1.25rem;">

  <div style="display: flex; align-items: center; gap: 12px;
              margin-bottom: 16px;">
    <!-- Avatar circle with initials -->
    <div style="width: 44px; height: 44px; border-radius: 50%;
                background: var(--color-background-info);
                display: flex; align-items: center; justify-content: center;
                font-weight: 500; font-size: 14px;
                color: var(--color-text-info);">JD</div>
    <div>
      <p style="font-weight: 500; font-size: 15px; margin: 0;">Jane Doe</p>
      <p style="font-size: 13px; color: var(--color-text-secondary);
                margin: 0;">Lead Engineer</p>
    </div>
  </div>

  <div style="border-top: 0.5px solid var(--color-border-tertiary);
              padding-top: 12px;">
    <table style="width: 100%; font-size: 13px;">
      <tr>
        <td style="color: var(--color-text-secondary); padding: 4px 0;">
          Email</td>
        <td style="text-align: right; padding: 4px 0;
                   color: var(--color-text-info);">[e-mail]</td>
      </tr>
    </table>
  </div>
</div>

Badges and Status Pills

<!-- Status badge -->
<span style="display: inline-block; font-size: 12px; padding: 4px 12px;
             border-radius: var(--border-radius-md);
             background: var(--color-background-success);
             color: var(--color-text-success);">Active</span>

<!-- Featured accent (the ONLY case where 2px border is allowed) -->
<div style="border: 2px solid var(--color-border-info);
            border-radius: var(--border-radius-lg);
            padding: 1rem 1.25rem;">
  <span style="font-size: 12px; padding: 4px 12px;
               border-radius: var(--border-radius-md);
               background: var(--color-background-info);
               color: var(--color-text-info);">Most popular</span>
</div>

Form Elements

Inputs, selects, textareas, buttons, and range sliders are pre-styled in the host environment. Write bare tags — they inherit correct styling:

• Text inputs: 36px height, hover/focus states built in
• Range sliders: 4px track + 18px thumb
• Buttons: transparent bg, 0.5px border, hover/active states

Never use <form> tags. Use onClick / onChange handlers directly.

Comparison Cards

For "help me choose between X and Y":

<div style="display: grid; grid-template-columns:
            repeat(auto-fit, minmax(160px, 1fr)); gap: 12px;">

  <div style="background: var(--color-background-primary);
              border: 0.5px solid var(--color-border-tertiary);
              border-radius: var(--border-radius-lg);
              padding: 1rem 1.25rem;">
    <h3 style="font-size: 16px; font-weight: 500; margin: 0 0 8px;">
      Option A</h3>
    <p style="font-size: 13px; color: var(--color-text-secondary);
              margin: 0;">Description here</p>
  </div>

  <!-- Repeat for Option B, C... -->
</div>

---

Part 3: Advanced Interactive Widgets

Simulations and Physics

For teaching physics, algorithms, or systems behavior with real-time updates.

Pattern: Animation Loop with Controls

<style>
  .sim-controls {
    display: flex; align-items: center; gap: 16px;
    margin: 12px 0; font-size: 13px;
    color: var(--color-text-secondary);
  }
</style>

<canvas id="sim" style="width: 100%; height: 300px;
        border-radius: var(--border-radius-md);
        background: var(--color-background-secondary);"></canvas>

<div class="sim-controls">
  <button onclick="toggleSim()">Play / Pause</button>
  <label>Speed
    <input type="range" min="1" max="10" value="5" id="speed"
           oninput="simSpeed=+this.value">
  </label>
  <button onclick="resetSim()">Reset</button>
</div>

<script>
const canvas = document.getElementById('sim');
const ctx = canvas.getContext('2d');
let running = true, simSpeed = 5, animId;

function resizeCanvas() {
  canvas.width = canvas.offsetWidth;
  canvas.height = canvas.offsetHeight;
}
resizeCanvas();

// State
let particles = [];
function init() {
  particles = Array.from({length: 50}, () => ({
    x: Math.random() * canvas.width,
    y: Math.random() * canvas.height,
    vx: (Math.random() - 0.5) * 2,
    vy: (Math.random() - 0.5) * 2
  }));
}

function step() {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  for (const p of particles) {
    p.x += p.vx * simSpeed * 0.2;
    p.y += p.vy * simSpeed * 0.2;
    if (p.x < 0 || p.x > canvas.width) p.vx *= -1;
    if (p.y < 0 || p.y > canvas.height) p.vy *= -1;
    ctx.beginPath();
    ctx.arc(p.x, p.y, 4, 0, Math.PI * 2);
    ctx.fillStyle = '#534AB7';
    ctx.fill();
  }
  if (running) animId = requestAnimationFrame(step);
}

function toggleSim() { running = !running; if (running) step(); }
function resetSim() { init(); if (!running) { running = true; step(); } }

init();
step();
</script>

Math Visualizations

For plotting functions, showing geometric relationships, or exploring equations.

Pattern: Function Plotter with SVG

<svg id="plot" width="100%" viewBox="0 0 680 400">
  <!-- Grid -->
  <line x1="60" y1="200" x2="640" y2="200"
        stroke="var(--color-border-tertiary)" stroke-width="0.5"/>
  <line x1="340" y1="20" x2="340" y2="380"
        stroke="var(--color-border-tertiary)" stroke-width="0.5"/>
  <!-- Axes labels -->
  <text x="645" y="196" font-size="12"
        fill="var(--color-text-tertiary)">x</text>
  <text x="345" y="16" font-size="12"
        fill="var(--color-text-tertiary)">y</text>
  <!-- Function path drawn by JS -->
  <path id="fn-path" fill="none" stroke="#534AB7" stroke-width="2"/>
</svg>

<div style="display:flex;gap:16px;align-items:center;margin:12px 0;
            font-size:13px;color:var(--color-text-secondary)">
  <label>f(x) = sin(
    <input type="number" id="freq" value="1" min="0.1" max="10" step="0.1"
           style="width:60px" oninput="plotFn()">x)
  </label>
  <label>Amplitude
    <input type="range" id="amp" min="0.1" max="3" value="1" step="0.1"
           style="flex:1" oninput="plotFn()">
  </label>
</div>

<script>
function plotFn() {
  const freq = +document.getElementById('freq').value;
  const amp = +document.getElementById('amp').value;
  const xMin = -5, xMax = 5, yMin = -3, yMax = 3;
  const toSvgX = x => 60 + (x - xMin) / (xMax - xMin) * 580;
  const toSvgY = y => 20 + (yMax - y) / (yMax - yMin) * 360;
  let d = '';
  for (let px = 0; px <= 580; px++) {
    const x = xMin + px / 580 * (xMax - xMin);
    const y = amp * Math.sin(freq * x);
    d += (px === 0 ? 'M' : 'L') + toSvgX(x).toFixed(1)
       + ' ' + toSvgY(y).toFixed(1);
  }
  document.getElementById('fn-path').setAttribute('d', d);
}
plotFn();
</script>

Sortable / Filterable Data Tables

<style>
  .data-table { width: 100%; border-collapse: collapse; font-size: 14px; }
  .data-table th {
    text-align: left; padding: 8px 12px; font-weight: 500;
    border-bottom: 0.5px solid var(--color-border-secondary);
    color: var(--color-text-secondary); cursor: pointer;
    user-select: none; font-size: 12px;
  }
  .data-table th:hover { color: var(--color-text-primary); }
  .data-table td {
    padding: 8px 12px;
    border-bottom: 0.5px solid var(--color-border-tertiary);
  }
</style>

<input type="text" placeholder="Filter..."
       oninput="filterTable(this.value)"
       style="width: 100%; margin-bottom: 12px;">

<table class="data-table" id="table">
  <thead>
    <tr>
      <th onclick="sortTable(0)">Name</th>
      <th onclick="sortTable(1)">Value</th>
      <th onclick="sortTable(2)">Status</th>
    </tr>
  </thead>
  <tbody id="tbody">
    <!-- Rows populated by JS -->
  </tbody>
</table>

<script>
const data = [
  ['Alpha', 42, 'Active'],
  ['Beta', 18, 'Paused'],
  ['Gamma', 91, 'Active'],
];
let sortCol = -1, sortAsc = true;

function render(rows) {
  document.getElementById('tbody').innerHTML = rows.map(r =>
    `<tr><td>${r[0]}</td><td>${r[1]}</td>
     <td><span style="font-size:12px;padding:2px 10px;
       border-radius:var(--border-radius-md);
       background:var(--color-background-${r[2]==='Active'?'success':'warning'});
       color:var(--color-text-${r[2]==='Active'?'success':'warning'})">${r[2]}</span>
     </td></tr>`
  ).join('');
}

function sortTable(col) {
  sortAsc = sortCol === col ? !sortAsc : true;
  sortCol = col;
  data.sort((a, b) => {
    if (a[col] < b[col]) return sortAsc ? -1 : 1;
    if (a[col] > b[col]) return sortAsc ? 1 : -1;
    return 0;
  });
  render(data);
}

function filterTable(q) {
  const low = q.toLowerCase();
  render(data.filter(r => r.some(c => String(c).toLowerCase().includes(low))));
}

render(data);
</script>

---

Part 4: Chart.js — Advanced Patterns

Dark Mode Awareness

const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const textColor = isDark ? '#c2c0b6' : '#3d3d3a';
const gridColor = isDark ? 'rgba(255,255,255,0.08)' : 'rgba(0,0,0,0.06)';
const tooltipBg = isDark ? '#2C2C2A' : '#fff';

Canvas cannot read CSS variables — always detect dark mode and use hardcoded hex values.

Wrapper Pattern (Critical for Sizing)

<div style="position: relative; width: 100%; height: 300px;">
  <canvas id="chart"></canvas>
</div>

• Height goes on the wrapper div ONLY, never on canvas.
• Always set responsive: true, maintainAspectRatio: false.
• For horizontal bar charts: height = (bars x 40) + 80 pixels.

Custom Legend (Always Use This)

Disable Chart.js default legend and build HTML:

plugins: { legend: { display: false } }

<div style="display: flex; flex-wrap: wrap; gap: 16px;
            margin-bottom: 8px; font-size: 12px;
            color: var(--color-text-secondary);">
  <span style="display: flex; align-items: center; gap: 4px;">
    <span style="width: 10px; height: 10px; border-radius: 2px;
                 background: #534AB7;"></span>Series A — 65%
  </span>
  <span style="display: flex; align-items: center; gap: 4px;">
    <span style="width: 10px; height: 10px; border-radius: 2px;
                 background: #0F6E56;"></span>Series B — 35%
  </span>
</div>

Dashboard Layout

Metric cards on top -> chart below -> sendPrompt for drill-down:

<!-- Metric cards grid -->
<div style="display: grid;
            grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
            gap: 12px; margin-bottom: 1.5rem;">
  <!-- cards here -->
</div>

<!-- Chart (no card wrapper) -->
<div style="position: relative; width: 100%; height: 300px;">
  <canvas id="chart"></canvas>
</div>

Chart Type Selection Guide

Data pattern	Chart type
Trend over time	Line
Category comparison	Vertical bar
Ranking (few items)	Horizontal bar
Part of whole	Doughnut
Distribution	Histogram (bar)
Correlation (2 variables)	Scatter
Multi-variable comparison	Radar
Range / uncertainty	Line with fill area

---

Part 5: Generative Art and Illustration

For when the user asks for something creative, decorative, or aesthetic.

When to Use

• "Draw me a sunset" / "Create a pattern"
• Decorative headers or visual breaks
• Mood illustrations for creative writing
• Abstract visualizations of data or music

Rules (Different from Diagrams)

• Fill the canvas — art should feel rich, not sparse
• Bold colors are encouraged. You can use custom hex freely.
• Layered overlapping shapes create depth
• Organic forms with <path> curves, <ellipse>, <circle>
• Texture via repetition (hatching, dots, parallel lines)
• Geometric patterns with <g transform="rotate()">
• NO gradients, shadows, blur, or glow (still flat aesthetic)

Pattern: Geometric Art

<svg width="100%" viewBox="0 0 680 400">
  <!-- Background shapes -->
  <circle cx="200" cy="200" r="150" fill="#EEEDFE" opacity="0.8"/>
  <circle cx="480" cy="180" r="120" fill="#E1F5EE" opacity="0.8"/>

  <!-- Overlapping geometric forms -->
  <rect x="150" y="100" width="200" height="200" rx="8"
        fill="#CECBF6" opacity="0.6"
        transform="rotate(15 250 200)"/>
  <rect x="320" y="80" width="180" height="180" rx="8"
        fill="#9FE1CB" opacity="0.6"
        transform="rotate(-10 410 170)"/>

  <!-- Detail lines -->
  <line x1="100" y1="300" x2="580" y2="300"
        stroke="#534AB7" stroke-width="0.5" opacity="0.3"/>
  <line x1="100" y1="310" x2="580" y2="310"
        stroke="#534AB7" stroke-width="0.5" opacity="0.2"/>
</svg>

Pattern: Radial Symmetry

<svg width="100%" viewBox="0 0 680 680">
  <g transform="translate(340 340)">
    <!-- Repeat a shape at angular intervals -->
    <g transform="rotate(0)">
      <ellipse cx="0" cy="-120" rx="30" ry="80"
               fill="#FAECE7" stroke="#993C1D" stroke-width="0.5"/>
    </g>
    <g transform="rotate(45)">
      <ellipse cx="0" cy="-120" rx="30" ry="80"
               fill="#FBEAF0" stroke="#993556" stroke-width="0.5"/>
    </g>
    <!-- ... repeat for 90, 135, 180, 225, 270, 315 -->
  </g>
</svg>

Pattern: Landscape with Layered Shapes

For physical scenes, use ALL hardcoded hex (no theme classes):

<svg width="100%" viewBox="0 0 680 400">
  <!-- Sky -->
  <rect x="0" y="0" width="680" height="250" fill="#E6F1FB"/>
  <!-- Mountains -->
  <polygon points="0,250 150,100 300,250" fill="#B4B2A9"/>
  <polygon points="200,250 400,60 600,250" fill="#888780"/>
  <!-- Ground -->
  <rect x="0" y="250" width="680" height="150" fill="#C0DD97"/>
  <!-- Sun -->
  <circle cx="550" cy="80" r="40" fill="#FAC775"/>
</svg>

---

Part 6: Advanced Patterns

Tabbed / Multi-View Interfaces

Since content streams top-down, don't use display: none during streaming. Instead, render all content stacked, then use post-stream JS to create tabs:

<div id="tabs" style="display:flex;gap:4px;margin-bottom:16px;">
  <button onclick="showTab(0)" style="font-weight:500">Overview</button>
  <button onclick="showTab(1)">Details</button>
  <button onclick="showTab(2)">Code</button>
</div>

<div id="panel-0"><!-- Overview content --></div>
<div id="panel-1"><!-- Details content --></div>
<div id="panel-2"><!-- Code content --></div>

<script>
function showTab(n) {
  for (let i = 0; i < 3; i++) {
    document.getElementById('panel-' + i).style.display =
      i === n ? 'block' : 'none';
  }
  document.querySelectorAll('#tabs button').forEach((b, i) => {
    b.style.fontWeight = i === n ? '500' : '400';
    b.style.color = i === n
      ? 'var(--color-text-primary)' : 'var(--color-text-tertiary)';
  });
}
showTab(0);
</script>

sendPrompt() — Chat-Driven Interactivity

A global function that sends a message as if the user typed it. Use it when the user's next action benefits from AI thinking:

<button onclick="sendPrompt('Break down Q4 revenue by region')">
  Drill into Q4 ↗
</button>
<button onclick="sendPrompt('Explain what shear force is')">
  Learn about shear ↗
</button>

Use for: drill-downs, follow-up questions, "explain this part". Don't use for: filtering, sorting, toggling — handle those in JS. Append ↗ to button text when it triggers sendPrompt.

Responsive Grid Pattern

display: grid;
grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
gap: 12px;

Use minmax(0, 1fr) if children have large min-content that could overflow.

CSS Animations (Subtle and Purposeful)

/* Only animate transform and opacity for performance */
@keyframes fadeSlideIn {
  from { opacity: 0; transform: translateY(8px); }
  to { opacity: 1; transform: translateY(0); }
}

/* Always respect user preferences */
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
  }
}

/* Flowing particles / convection currents */
@keyframes flow { to { stroke-dashoffset: -20; } }
.flowing {
  stroke-dasharray: 5 5;
  animation: flow 1.6s linear infinite;
}

/* Pulsing for active elements */
@keyframes pulse {
  0%, 100% { opacity: 0.3; }
  50% { opacity: 0.7; }
}

---

Part 7: External Libraries (CDN Allowlist)

Only these CDN origins work (CSP-enforced):

• cdnjs.cloudflare.com
• esm.sh
• cdn.jsdelivr.net
• unpkg.com

Useful Libraries

Chart.js (data visualization):

<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.js"></script>

Three.js (3D graphics) — use ES module import (import map resolves bare specifiers):

<script type="module">
import * as THREE from 'three';
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
// ... your Three.js code here
</script>

Alternative UMD (global THREE variable):

<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>

D3.js (advanced data viz, force layouts, geographic maps):

<script src="https://cdnjs.cloudflare.com/ajax/libs/d3/7.9.0/d3.min.js"></script>

Mermaid (ERDs, sequence diagrams, class diagrams):

<script type="module">
import mermaid from 'https://esm.sh/mermaid@11/dist/mermaid.esm.min.mjs';
</script>

Tone.js (audio synthesis):

<script src="https://cdnjs.cloudflare.com/ajax/libs/tone/14.8.49/Tone.min.js"></script>

Three.js Coordinate Conventions

Three.js uses a right-handed Y-up coordinate system:

• X = right (positive) / left (negative)
• Y = up (positive) / down (negative)
• Z = toward the viewer (positive) / away from the viewer (negative)

Critical for vehicles and aircraft: The fuselage/body extends along Z (nose at -Z, tail at +Z). Wings extend along X (left/right). The vertical stabilizer extends along Y.

When building an aircraft from primitives:

• Fuselage = cylinder or box, long axis along Z (use geometry default or rotate 90° around X)
• Wings = flat box, wide along X, thin along Y, short along Z
• Tail fin = flat box, tall along Y, thin along X, short along Z

// Correct aircraft orientation example:
// Fuselage along Z
const fuselage = new THREE.Mesh(
  new THREE.CylinderGeometry(0.15, 0.08, 2.0, 12),
  material
);
fuselage.rotation.x = Math.PI / 2; // CylinderGeometry default is Y-up, rotate to Z-forward

// Wings along X
const wing = new THREE.Mesh(
  new THREE.BoxGeometry(2.5, 0.03, 0.4), // wide X, thin Y, short Z
  material
);

// Vertical stabilizer along Y
const tailFin = new THREE.Mesh(
  new THREE.BoxGeometry(0.03, 0.4, 0.3), // thin X, tall Y, short Z
  material
);
tailFin.position.set(0, 0.2, 0.9); // above and behind

Rotation axes for flight dynamics:

• Pitch = rotation around X (nose up/down)
• Roll = rotation around Z (wings tilt)
• Yaw = rotation around Y (nose left/right)

Common mistake: Using the wing box as the fuselage (wide along X instead of Z). Always verify: the longest dimension of the fuselage should be along Z.

---

Part 8: Quality Checklist

Before producing any visual, run through this:

Functional

• Does it work without JavaScript during streaming? (Content visible)
• Do all interactive controls have event handlers?
• Are all displayed numbers rounded properly?
• Does the canvas/SVG fit within the container width?

Visual

• Dark mode test: would every element be readable on near-black?
• No hardcoded text colors in HTML (use CSS variables)
• No gradients, shadows, blur, or glow
• Borders are 0.5px (except 2px for featured item accent)
• Font weights are only 400 or 500
• All text is sentence case

Content

• Explanatory text is in the response, not inside the widget
• No titles or headings embedded in the HTML output
• Visual is self-explanatory without reading the narration
• Narration adds value beyond what the visual shows
• Offered a clear "go deeper" path

Accessibility

• @media (prefers-reduced-motion: reduce) for all animations
• Text contrast is sufficient (dark text on light fills, vice versa)
• Interactive elements are large enough to click (min 44px touch target)
• No information conveyed by color alone

---

Part 9: Decision Matrix — Picking the Right Visual

User asks about...	Output type	Technology
How X works (physical)	Illustrative diagram	SVG
How X works (abstract)	Interactive explainer	HTML + inline SVG
Process / steps	Flowchart	SVG
Architecture / containment	Structural diagram	SVG
Database schema / ERD	Relationship diagram	Mermaid
Trends over time	Line chart	Chart.js
Category comparison	Bar chart	Chart.js
Part of whole	Doughnut chart	Chart.js
KPIs / metrics	Dashboard	HTML metric cards
Design a UI	Mockup	HTML
Choose between options	Comparison cards	HTML grid
Cyclic process	Step-through	HTML stepper
Physics / math	Simulation	Canvas + JS
Function / equation	Plotter	SVG + JS
Data exploration	Sortable table	HTML + JS
Creative / decorative	Art / illustration	SVG
3D visualization	3D scene	Three.js
Music / audio	Synthesizer	Tone.js
Network / graph	Force layout	D3.js
Quick factual answer	Plain text	None
Code solution	Code block	None
Emotional support	Warm text	None