Build Web Data Visualization

View saved version →

---
name: accessibility-and-inclusive-visualization
description: Make data visualizations accessible and inclusive. Use when the user needs chart or diagram accessibility guidance, text alternatives for complex visuals, color and contrast review, keyboard support, reduced-motion behavior for animation or parallax, or an accessibility QA workflow for exported figures, UML-like diagrams, and dashboards.
---

# Accessibility and Inclusive Visualization

## Overview

Use this skill when a visualization must be understandable by more people, in more contexts, with more assistive needs. Accessibility is not a post-processing step. It shapes chart selection, color, labeling, interaction, fallback text, and export strategy.

Default assumption: every important visualization should have a non-visual path to the key insight, whether through surrounding text, direct labels, data tables, or formal text alternatives.

## Working Pattern

1. Identify whether the chart is exploratory, explanatory, interactive, or exported.
2. Decide which information must remain available without hover, color discrimination, pointer precision, expanded panels, private persisted state, permission-gated capabilities, or a strong connection.
3. If the story uses generated imagery, illustration, WebGL, particles, 3D, maps, scrollytelling, parallax, or animation, separate what the asset shows from what the data proves.
4. If Codex image generation was used for a layout, figure, page-integration, asset, or key-frame concept, verify that the large-screen and mobile concept images were shown with concise plan and interaction bullets, the user approved the generated design set before project changes or implementation code began, and the semantic design contract from `../../references/foundations/meaning-preserving-visual-design-workflow.md` exists: the accessible path must preserve the same claim, caveat, source context, evidence hierarchy, locked layout elements, mobile continuation, and interaction meaning as the visual design.
5. If the view is a UML-like, ERD, state machine, workflow, dependency, or architecture diagram, preserve a text outline of nodes, groups, relationships, and selected paths; use `../uml-and-software-architecture-visualization/SKILL.md` for diagram-specific semantics.
6. Use `../../references/foundations/mobile-first-responsive-visualization.md` to verify touch targets, drag alternatives, keyboard-open visual viewport behavior, main-visualization visibility, spotty-connection states, and fallbacks for AR, camera, motion, vibration, notifications, and geolocation.
7. Provide direct labels, strong contrast, redundant encodings, keyboard paths, reduced-motion alternatives, accessible disclosure controls, and text alternatives.
8. For interactive visualizations, check that shared URLs, saved views, refresh, and back/forward navigation preserve the same accessible state summaries as the visual surface.
9. Test both the chart or diagram and the surrounding narrative.

## Output Expectations

- Name the accessibility risks specific to the chart, not just generic WCAG items.
- Provide fallback strategies for screen readers, PDFs, and static exports.
- Explain what to keep visible without relying on hover or color alone.
- Explain which active filters, selections, caveats, and summary values remain visible when configuration or drill-down panels are collapsed.
- For color guidance, name the semantic color roles, contrast risks, redundant encodings, and grayscale or color-deficiency review path.
- For image-supported visual stories, provide alt text or long descriptions that cover the scene, the data layer, the main takeaway, and the caveat without overstating generated imagery.
- For concepted visualizations, make sure the user approval record exists and the long description, reduced-motion path, static export, and source/caveat text preserve the approved semantic design contract and locked concept elements, not just the final rendered pixels.
- For mobile visualizations, make sure the main evidence is not pushed below settings, touch targets and hit areas are large enough, drag has alternatives, hover has tap/focus equivalents, keyboard-open states remain operable, stale/offline states are named, and sensor/camera/notification features have non-permission fallbacks.
- For animation, specify reduced-motion behavior and key-frame or final-state fallback.
- For scrollytelling or parallax, preserve native scroll and keyboard behavior, specify static key frames or stacked fallback, and make sure motion can be disabled without losing the evidence.
- For WebGL or particle effects, describe the data meaning in text, expose keyboard-accessible focus or selection paths for important marks, and provide a non-animated fallback that preserves flow, direction, focus, and uncertainty.
- For interactive diagrams, make search, selection, details panels, reset, export, expand/collapse, and drill-down reachable without pointer-only interaction.
- For shareable visualizations, make copy-link, saved-view, reset, expanded/collapsed panels, and restored URL state reachable and understandable by keyboard and screen-reader users.

## References

- Shared theory:
  - `../../references/foundations/perception-color-and-encoding.md`
  - `../../references/foundations/storytelling-annotation-and-critique.md`
  - `../../references/foundations/meaning-preserving-visual-design-workflow.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
- Skill references:
  - `./references/text-alternatives-and-complex-images.md`
  - `./references/color-contrast-and-redundant-encoding.md`
  - `./references/keyboard-screen-reader-and-export.md`
  - `./references/testing-and-review-workflow.md`
  - `../uml-and-software-architecture-visualization/SKILL.md`
  - `../scrollytelling-and-parallax-data-visualization/references/accessibility-testing-and-review.md`

## Representative Prompts

- "Make this chart accessible."
- "How should I write alt text or a long description for this visualization?"
- "Review this dashboard for color, keyboard, and screen-reader issues."
- "What needs to change before this chart goes into a PDF report?"
- "How do I design tooltips and hover interactions without excluding people?"
- "Make this parallax scrollytelling visualization safe for reduced-motion users."
- "Make this UML, ERD, workflow, state machine, or architecture diagram accessible."

Referenced files: 5

View saved version →

---
name: canvas2d-data-visualization
description: Render data visualizations with Canvas2D. Use when the visualization needs high mark counts, fast redraws, immediate-mode rendering, custom hit testing, or a hybrid Canvas plus SVG or HTML architecture.
---

# Canvas2D Data Visualization

## Overview

Use this skill when raster rendering is the practical choice. Canvas2D is strong for dense scatterplots, sparkline walls, heatmaps, streaming traces, tiled timelines, draggable analytical workspaces, and other views where SVG or DOM overhead becomes the limiting factor.

Default assumption: keep a retained scene model in application state even if the actual drawing is immediate-mode Canvas.
Any visualization or interaction that can be built in SVG can usually be built in Canvas2D too, but the retained geometry, hit testing, focus model, and accessibility layer become the application's responsibility. Choose Canvas for performance or rendering control; keep SVG/HTML when native DOM semantics, text, accessibility, or exportability matter more than redraw speed.
Canvas2D can also be simpler or faster than WebGL for flat immediate-mode workloads because it avoids shader setup, buffer uploads, GPU context pressure, and custom WebGL lifecycle code. Move from Canvas2D to WebGL when GPU picking, shader effects, particle count, custom blending, smooth animation, true 3D, or high-volume geospatial layers justify that extra complexity.

For browser-facing Canvas work, use `../../references/foundations/mobile-first-responsive-visualization.md` so backing-store size, hit testing, touch gestures, keyboard overlays, spotty connection states, and mobile performance budgets are part of the design contract.

## Choose Canvas2D When

- the chart needs tens of thousands to millions of marks
- panning or zooming must feel fluid
- the view updates continuously
- the page needs many repeated microcharts such as sparklines in tables or KPI grids
- many chart instances are visible at once and SVG node count would dominate layout, style, and memory cost
- marks need custom clickable, hoverable, brushable, or draggable behavior over dense geometry
- you can tolerate raster output or provide separate export paths
- the chart benefits from layered drawing control, including static contextual backgrounds behind dense marks

Prefer SVG, HTML, or a declarative grammar when the chart is small, static, text-heavy, annotation-heavy, primarily accessibility-driven, or needs straightforward copy/paste/editable-vector export.
Prefer WebGL or the Three.js/WebGL skill when the chart needs GPU-scale particles, custom shaders, instancing, very large graph or point layers, 3D, or map overlays that Canvas2D would struggle to animate or pick interactively.

## Core Practices

1. Scale the backing store for browser zoom and high-DPI output:
   - set CSS `style.width` and `style.height` in CSS pixels
   - set the `canvas.width` and `canvas.height` attributes to `cssSize * pixelRatio`
   - use `globalThis.devicePixelRatio || 1` as the page-zoom-aware ratio
   - consider `visualViewport.scale` only when deliberately redrawing for pinch-zoom crispness
   - reset the context with `ctx.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0)` so drawing code can stay in CSS pixels
2. Keep world-to-screen transforms explicit.
3. Use layered canvases for:
   - static background, including any field, court, floor plan, schematic, or other contextual surface
   - primary marks
   - highlight or hover state
   - interaction overlays
4. Avoid full redraws when partial invalidation is possible.
5. Build deterministic hit testing:
   - spatial index
   - color picking buffer
   - nearest-point search
   - `Path2D` geometry replay against candidate subsets with `isPointInPath()` and `isPointInStroke()`
   - analytic tests for simple shapes such as points, line segments, rectangles, intervals, and bands
6. Assess how many Canvas instances may be visible at once, because backing-store size and redraw cost multiply quickly at dashboard scale.
7. Treat pointer interaction as a first-class subsystem:
   - normalize `PointerEvent.clientX/clientY` through `getBoundingClientRect()`
   - invert the current pan/zoom transform before mapping to data coordinates
   - use `setPointerCapture()` for drags so movement continues outside the canvas
   - clean up drag state on `pointerup`, `pointercancel`, and `lostpointercapture`
   - use `touch-action` deliberately for touch and pen surfaces
   - provide non-drag alternatives and enlarged invisible hit regions for small marks on coarse pointers
   - keep keyboard and screen-reader affordances in HTML when Canvas marks are semantically important
8. For mobile, define whether one-finger drag pans the chart or scrolls the page, whether pinch zoom is chart-owned or browser-owned, and how reset or explicit zoom controls work.

## Hybrid Architecture

- Canvas for bulk marks
- SVG or HTML for axes, labels, legends, rich tooltips, menus, form controls, keyboard focus, and annotations
- shared scales and transforms across both layers

This is usually better than forcing all responsibilities into Canvas. Use absolutely positioned HTML overlays for elements that need native layout, selection, input, focus rings, links, or accessible semantics; keep them synchronized by deriving every overlay position from the same world-to-screen transform used by the Canvas renderer.
For sparklines and other microcharts, nearby row labels, headers, and inline values usually work better than a shared detached legend.

## Performance Defaults

- batch draw calls
- precompute style groups
- use typed arrays for geometry-heavy views
- cull off-screen marks
- decimate or aggregate when the viewport cannot resolve individual points
- use `OffscreenCanvas` and workers when main-thread contention is significant
- keep text and annotations in HTML or SVG unless Canvas text is genuinely required
- prefer one shared Canvas layer or virtualization for large sparkline tables instead of hundreds of independent backing stores when memory becomes visible
- compute backing-store memory as `width * height * pixelRatio^2 * 4 * layerCount * instanceCount`
- cap pixel ratio or quality on mobile when memory, battery, or thermal pressure would outweigh crispness
- keep stale/offline/partial-data overlays in HTML or a light Canvas layer instead of blanking the chart during network recovery
- use `getContext("2d", { willReadFrequently: true })` only for canvases that repeatedly call `getImageData()`, such as color-picking buffers

## Output Expectations

- Explain why Canvas is better than SVG for the workload.
- If SVG could also work, name the interaction, accessibility, and maintenance costs Canvas introduces and why the performance tradeoff is still worth it.
- Keep labels and accessibility strategy explicit.
- For sparkline-heavy views, explain how the surrounding table or card context carries meaning without forcing legend lookup.
- For clickable or draggable Canvas views, specify the hit-testing strategy and how pointer coordinates map to data coordinates.
- For mobile Canvas views, specify touch target policy, pointer capture, drag alternatives, pinch/zoom ownership, visual viewport or keyboard behavior, DPR cap, and low-bandwidth/stale-data behavior when relevant.
- For color-picking buffers, specify id encoding, alpha and antialiasing assumptions, `getImageData()` readback cost, and when the buffer invalidates.
- For zoomable or resizable Canvas views, specify how CSS size, backing-store attributes, `devicePixelRatio`, and redraw invalidation are handled.
- For HTML overlays, specify which layer owns pointer events, focus, tooltip positioning, and accessibility semantics.
- If a contextual surface is part of the design, document its source geometry and keep overlays, labels, and hit testing aligned to the same coordinate transform.
- Preserve a path to exported assets, usually via PNG plus optional vector companion views.
- For new work, include a technical design section covering simultaneous instance count, memory and redraw cost per instance, and maintenance tradeoffs of the hybrid architecture.

## References

- Shared theory:
  - `../../references/foundations/perception-color-and-encoding.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
  - `../../references/foundations/domain-contextual-surfaces.md`
  - `../../references/foundations/implementation-design-and-tradeoffs.md`
- Skill references:
  - `./references/rendering-architecture.md`
  - `./references/high-density-interaction.md`
  - `./references/performance-playbook.md`
  - `./references/sparklines-and-microcharts.md`

## Representative Prompts

- "Render a million-point scatterplot in the browser."
- "Build a fast Canvas timeline with brushing and zoom."
- "Move this SVG heatmap to Canvas without losing labels."
- "Render sparklines for every row in a data table."
- "Design hit testing for a dense Canvas chart."
- "Explain how to split this visualization across multiple Canvas layers."
- "Make these Canvas marks clickable and draggable."
- "Fix this blurry Canvas chart when the browser is zoomed."

Referenced files: 5

View saved version →

---
name: d3-data-visualization
description: Build custom data visualizations with D3. Use when the user needs SVG or DOM-based charts, rich annotation, domain-native contextual backgrounds, data joins, custom scales or interactions, scroll-driven SVG scene states, or precise control over browser visualization behavior.
---

# D3 Data Visualization

## Overview

Use this skill for custom browser visualizations where SVG or DOM semantics matter and a declarative grammar no longer fits cleanly. D3 is strongest when the chart needs bespoke scales, marks, layouts, transitions, zooming, brushing, annotations, or vector export.

Default assumption: use D3 for scales, layouts, geometry, labels, annotation layers, and behavior. Do not turn D3 into the entire application architecture if a framework already owns the surrounding UI.

## Choose D3 When

- the chart needs custom marks or nonstandard layouts
- SVG quality matters for export, print, or accessibility
- annotation and labeling are part of the design, not an afterthought
- the visualization needs custom vector background geometry such as a field, court, track, floor plan, schematic, or other meaningful contextual surface
- an editorial story needs data-bound generated cutouts, illustrated substrates, scrollytelling/parallax states, or animated annotation reveals in SVG
- the mark count is moderate enough for DOM or SVG
- the interaction model needs zoom, brush, drag, or coordinated views
- a UML-like, dependency, architecture, state, or flow diagram needs bespoke SVG annotation or product-specific composition after `../uml-and-software-architecture-visualization/SKILL.md` has defined the diagram semantics
- a declarative grammar would become harder to read than the resulting D3 code

## Avoid D3-First DOM Rendering When

- mark counts are so large that DOM throughput becomes the bottleneck
- animation is continuous and frame budgets are tight
- the task would be faster to solve with Canvas2D or WebGL

## Working Pattern

1. Build a clean data model first.
2. Separate:
   - parsing and normalization
   - scale construction
   - derived geometry
   - rendering
   - interaction state
3. Prefer stable keys in joins.
4. Use D3 for math and behavior, not for hiding weak state management.
5. Assess how many D3 instances may coexist on the page so DOM, layout, and event costs are evaluated at dashboard scale.
6. If using a contextual surface, keep source units and render scales explicit, draw the background as a separate layer, and adapt mark placement or layout forces to the domain geometry.
7. For art-directed stories, keep generated image, substrate, data-mark, label, and annotation layers separate so each can be reviewed and exported.
8. Keep annotations and interaction overlays explicit.
9. For SVG output, apply `./references/svg-polish-and-crispness.md` before calling the chart finished. Explicitly set font sizes, tick padding, gridline strokes, data stroke widths, icon sizes, label alignment, and zoom-stable stroke behavior.
10. For browser-facing work, use `../../references/foundations/mobile-first-responsive-visualization.md` so the D3 layout is recomputed for large-screen and mobile states rather than scaled down from one desktop SVG.

## Editorial Defaults

- Build an explicit label layer. Direct end labels, inline keys, or panel labels should be considered before a detached legend.
- Build an explicit annotation layer. Callouts should attach to data points, ranges, thresholds, or domain geometry rather than floating as decoration.
- Keep gridlines, axes, and reference marks quiet. Most ink should be data, labels, or annotation.
- Default SVG chart polish: 10-12 px axis ticks, 11-13.5 px direct labels, 0.5-1 px non-data strokes, 1.5-2.25 px normal data lines, 2.5-3 px focus lines, short 4-6 px ticks, and no heavy chart border unless it carries meaning.
- Use D3 axes as geometry generators, then style them. Prefer `.tickSizeOuter(0)`, 6-8 px tick padding, quiet gridlines, removed domains when redundant, and fewer ticks before rotated or tiny labels.
- Use `shape-rendering: crispEdges` for straight axes, gridlines, and rectangular cells; do not apply it globally to curves, symbols, circles, or diagonal marks.
- Use `vector-effect: non-scaling-stroke` for zoomable outlines, axes, annotation connectors, map borders, and icons that should keep screen-stable stroke weight.
- Use custom layout only when the story needs it; do not copy a publication's composition or visual identity.
- For narrow widths, provide either a simplified mark layout, small-multiple stack, or numbered annotation key below the chart.
- On mobile, make tap/focus the inspection path, enlarge hit areas beyond visible marks, provide drag alternatives, define pinch or zoom ownership, and keep the main chart visible when filters or settings open.
- Favor inspectable SVG for editorial charts that need export, accessibility, and precise labels. Move dense mark fields to Canvas only when the DOM count justifies it.
- For scrollytelling or parallax, use `../scrollytelling-and-parallax-data-visualization/SKILL.md` for the scroll narrative, then let D3 own scales, derived geometry, data joins, labels, and SVG transitions. Keep each scene valid as a still.
- For generated imagery, use D3/SVG for labels, anchors, masks, clipping, and data overlays rather than baking numbers into images.
- For motion, use transitions to reveal sequence, direction, accumulation, comparison, or mechanism. Respect reduced-motion with final-state rendering.
- For 3D-looking SVG, avoid perspective distortion unless it represents a real multiaxis surface; label axes and provide a flat fallback when needed.

## Core D3 Building Blocks

- `d3-array` for grouping, extent, ticks, and summaries
- `d3-scale` for position, color, and size mappings
- `d3-axis` for readable axes
- `d3-shape` for lines, areas, arcs, and symbol generation
- `d3-selection` and `d3-transition` for DOM behavior
- `d3-brush`, `d3-zoom`, and `d3-drag` for direct manipulation
- `d3-force`, `d3-hierarchy`, `d3-contour`, and other layouts only when their data structure fits

## Integration Rules

- In React or another UI framework, prefer framework-owned structure and D3-owned geometry, scales, and behaviors.
- For highly custom charts, a small imperative D3 island is fine if the boundary is clear.
- Keep responsive behavior tied to container measurements, not magic constants.
- Recompute labels, tick counts, annotation placement, collision rules, and plot height for mobile portrait and optional landscape sizes; do not only resize the outer `viewBox`.
- Prefer SVG for labels and annotations even in hybrid systems.
- Keep contextual background layers non-interactive unless they are part of selection, zoom, or hit testing.
- Move to Canvas or WebGL when DOM count or continuous redraw becomes the limiting factor.

## Output Expectations

- Explain why D3 is the right rendering layer.
- Keep chart structure semantic and inspectable.
- Provide export paths for SVG or PNG when needed.
- Pair interaction with obvious annotation and reset controls.
- For mobile, state the touch target policy, hover replacement, drag/pinch ownership, and how the on-screen keyboard or settings panels return the user to the chart.
- When drawing a contextual surface, state the source geometry and how data marks are positioned, constrained, or biased by it.
- For image-supported editorial work, state which assets are generated, which layers remain data-bound, and how labels anchor to the substrate.
- For animation, state the verb, scene states, duration budget, and reduced-motion fallback.
- For new work, include a technical design section covering simultaneous instance count, DOM and interaction cost, and maintenance tradeoffs versus declarative or Canvas-based alternatives.

## References

- Shared theory:
  - `../../references/foundations/editorial-infographic-system.md`
  - `../../references/foundations/art-directed-interactive-visual-stories.md`
  - `../../references/foundations/perception-color-and-encoding.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
  - `../../references/foundations/domain-contextual-surfaces.md`
  - `../../references/foundations/storytelling-annotation-and-critique.md`
  - `../../references/foundations/implementation-design-and-tradeoffs.md`
- Skill references:
  - `./references/d3-module-map.md`
  - `./references/d3-architecture-patterns.md`
  - `./references/d3-interaction-and-annotation.md`
  - `./references/d3-pitfalls-and-scale-limits.md`
  - `./references/svg-polish-and-crispness.md`
  - `../uml-and-software-architecture-visualization/SKILL.md`
  - `../scrollytelling-and-parallax-data-visualization/SKILL.md`

## Representative Prompts

- "Build a D3 slopegraph with direct labels."
- "Add zoom and brushing to this scatterplot."
- "Create a publication-quality SVG chart from this dataset."
- "Draw a domain-accurate soccer pitch behind a player network and bias node positions by role."
- "Refactor this D3 chart so React owns layout and D3 owns math."
- "Animate this D3 chart through scrollytelling scene states."
- "Tell me when this D3 chart should move to Canvas."

Referenced files: 6

View saved version →

---
name: dashboards-and-real-time-visualization
description: Design dashboards and live visualization systems. Use when the user needs monitoring views, streaming charts, coordinated interactions, downsampling, or performance-aware operational visualization.
---

# Dashboards and Real-Time Visualization

## Overview

Use this skill when the visualization is a system, not a screenshot. That means update cadence, latency, interaction design, observability, and rendering budgets matter as much as chart choice.

If the main request is about how to test a live dashboard, freeze streams, mock refresh behavior, or cover alerting and stale states end to end, route first to `../testing-data-visualizations/SKILL.md`.

Mobile operational use is default unless explicitly excluded. Use `../../references/foundations/mobile-first-responsive-visualization.md` to plan the mobile portrait dashboard, optional landscape mode, touch interaction, on-screen keyboard behavior, spotty connection handling, and alerting or vibration strategy.

This skill covers three tightly related problems:

- real-time streaming and refresh behavior
- layout hierarchy and scan-first dashboard composition
- interaction patterns and coordinated views
- performance and scale

## Default Questions

1. What is the update model?
   - append-only stream
   - periodic polling
   - event bursts
   - full snapshot replacement
2. What latency matters?
   - sub-second monitoring
   - near-real-time operational review
   - asynchronous reporting
3. What must the user do?
   - notice anomalies
   - compare current versus historical
   - inspect causes
   - filter and drill down
4. What are the hard limits?
   - frame budget
   - memory budget
   - network budget
   - exportability
   - mobile bandwidth, battery, and thermal budget
5. How many visualization instances can be visible at once?
   - single focal chart
   - a few coordinated panels
   - many repeated tiles or sparklines
6. What mobile state must work under interruption?
   - spotty or offline connection
   - app backgrounding or tab visibility changes
   - one-handed use
   - alert acknowledgment
   - on-screen keyboard for filters or notes

## Real-Time Design Rules

- Show time windows clearly.
- Distinguish live data from historical context.
- Handle missing, late, and out-of-order events explicitly.
- Keep the last known good visualization visible during reconnects, with stale, delayed, partial, offline, and error states distinct from normal live data.
- Show last updated time and update cadence near the evidence.
- Use aggregation, downsampling, or rollups before raw point dumping.
- Provide alert thresholds, annotations, and state transitions, not just moving lines.
- Use vibration, system notifications, or push-style alerts only for user-requested and meaningful state changes; always provide an in-app visual and accessible alert path.
- Keep the most important metric stable in position and encoding.
- Keep keys with their charts: direct labels or chart-adjacent keys beat a shared legend parked elsewhere on the screen.
- Use sparklines and other microcharts when compact trend context helps scanning, but rely on nearby labels and values to carry meaning.
- Design dashboards around situation awareness, not around maximum tile count.
- Prefer self-explanatory panels and concise labels over instructional paragraphs scattered across the UI.

## Layout and Scanning Defaults

- Give the screen a clear focal path: current state first, then supporting context, then controls and secondary diagnostics.
- Avoid grids where every tile has equal visual weight unless the user truly needs uniform scanning across peers.
- Keep filters and toggles near the views they change instead of collecting everything in a distant control rail.
- Reserve callouts and narrative copy for anomalies, caveats, or actions. The normal state should be legible without tutorial text.
- Collapse or defer low-value controls so the live state stays visually dominant.
- On mobile, do not stack the filter rail or diagnostic controls before the live state. Use bottom sheets, drawers, tabs, or inline controls that return the user to the affected visualization after Apply, Cancel, Reset, or close.
- Use mobile landscape for monitoring views when a wide timeline, map, field, route, dense table, or multi-series trace is meaningfully clearer in a handheld wide orientation, but still provide a portrait summary.

## Interaction Patterns

- overview first, filter or focus, then details on demand
- overview plus detail
- focus plus context
- brush and link
- hover for preview, click for commitment
- tap/focus for preview, tap again or explicit action for commitment on touch devices
- drill-down and drill-through
- persistent selections that survive updates
- explicit reset and undo paths

Interactivity should reduce cognitive load, not hide essential context behind constant mouse movement.

For mobile dashboards, add step-through controls, search, or nearest-item selection for dense marks; do not rely on hover, pixel-perfect taps, or one-finger chart panning that traps page scroll.

## Performance Defaults

1. Budget for 16 ms frames only when truly needed.
2. Reduce work before optimizing code:
   - fewer marks
   - smarter aggregation
   - smaller repaint regions
   - lower-frequency updates where appropriate
3. Choose the renderer intentionally:
   - SVG for semantics and annotation
   - Canvas2D for dense 2D raster workloads
   - WebGL, deck.gl, PixiJS, Sigma.js, or Three.js for GPU-scale marks, maps, particles, graph rendering, or true 3D
4. Use ring buffers, viewport culling, and multi-resolution summaries for long-running live views.
5. Separate interaction state from render state so updates remain predictable.
6. Use particles or glow in dashboards only for active flow, alert state, focus, or recency. Avoid ambient motion that competes with monitoring.

## Output Expectations

- Describe the update model and failure modes.
- Describe mobile reconnect, stale-data, offline/partial-data, and low-bandwidth behavior.
- Explain what a user should understand at first scan before touching any controls.
- Explain what the mobile user sees first and how the main visualization remains visible around controls and keyboard input.
- Define the interaction contract before building widgets.
- State how the system degrades when data rate or mark count rises.
- Include a technical design section for new work covering simultaneous chart count, per-instance and page-level budgets, and maintenance implications of the chosen rendering strategy.
- Keep accessibility and export strategy visible.

## References

- Shared theory:
  - `../../references/foundations/storytelling-annotation-and-critique.md`
  - `../../references/foundations/layout-hierarchy-and-self-explanatory-ux.md`
  - `../../references/foundations/interaction-models-and-progressive-disclosure.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
  - `../../references/foundations/implementation-design-and-tradeoffs.md`
- Skill references:
  - `./references/monitoring-vs-analysis.md`
  - `./references/streaming-data-pipelines.md`
  - `./references/interaction-patterns.md`
  - `./references/performance-and-degradation.md`
  - `../testing-data-visualizations/SKILL.md`

## Representative Prompts

- "Build a real-time operations dashboard from a WebSocket feed."
- "Keep this live chart smooth with 100 updates per second."
- "Design brushing, cross-filtering, and annotations for this monitoring UI."
- "Tell me if this should be a dashboard or a report."
- "Critique this monitoring screen using operational dashboard principles."

Referenced files: 5

View saved version →

---
name: data-visualization
description: Route web data visualization work. Use when the user needs chart choice, visual critique, dashboards, maps or geospatial views, Gantt timelines, UML/software diagrams, scrollytelling, reports or exports, testing, accessibility, browser implementation, or concept-first visual design.
---

# Web Data Visualization

## Overview

Use this skill as the implicit orchestrator for the plugin. Classify the task, choose the smallest useful specialist skill set, and route before doing deep chart, renderer, testing, accessibility, or export work. Specialist skills stay explicit-only unless this router hands off to them.

Default stance: the best visualization is the simplest truthful view that answers the user's question with the least decoding burden. Preserve evidence quality first: correct task abstraction, trustworthy data treatment, visible caveats, direct labels, accessible encodings, mobile viability, shareable state, and QA. Do not default to dashboards, 3D, animation, generated imagery, particles, or WebGL unless they carry analytical meaning.

Contextual imagery, atmospheric marks, and motion must be evidence-bearing. Do not use broad translucent brush strokes, wispy ribbons, bokeh/orbs, cinematic wallpaper, stock-photo haze, or decorative gradients as substitutes for data layers. When motion, flow, density, intensity, or spread appears, encode it with measured or clearly schematic contours, sampled fields, trajectories, particles with a defined unit or meaning, or annotated layers.

Mobile is a primary surface. Unless the user explicitly excludes it, treat large-screen and mobile portrait as sibling states. Add mobile landscape when a wide substrate, AR/camera/motion, two-handed interaction, or keyboard-heavy workflow needs it.

## Router Workflow

1. Classify the analytical job: comparison/ranking, time change, distribution/uncertainty, correlation, composition/flow, hierarchy/network, software/system structure, schedule, monitoring, geography, or export/reporting.
2. Classify the data shape: tabular, time series, multivariate, matrix, tree/graph, semantic diagram source, schedule/project plan, geospatial, stream, or generated/simulated story data.
3. Lock delivery constraints: static vs interactive, exploratory vs explanatory, browser/dashboard/report/PDF/slides, reuse level, scale, update rate, export, large-screen/mobile states, touch/keyboard/pinch, sensors, alerting, bandwidth, and persistence.
4. Define the reading path before the renderer: insight title, immediate evidence, on-demand detail, labels/keys/controls, caveats, mobile order, and what should stay visible when panels collapse.
5. Plan state explicitly: URL-backed filters, selections, ranges, zoom/map/camera, tabs, drill-down, saved-view ids, local/IndexedDB/remote persistence, invalid state, copy-link, refresh, and back-button behavior.
6. Choose whether a contextual substrate helps: map, field/court/track, floor plan, system schematic, terrain, object cutaway, or other domain surface. Use it only when it improves orientation or mark placement.
7. Route to the narrowest specialist skill. If the request spans several visual layers, read `../../references/foundations/embedded-visualization-self-use.md`, inventory the layers, assign owners, and use specialist passes for substantial layers.
8. For new implementation work, include a compact technical design before coding: instance count, data/interaction profile, renderer ownership, URL/persistence contract, mobile performance, page-level cost, maintenance tradeoffs, fallbacks, and QA.
9. For advanced visual design, use `../../references/foundations/meaning-preserving-visual-design-workflow.md` and `../../references/foundations/mobile-first-responsive-visualization.md`; generate large-screen and mobile concepts, pause for approval, and treat approved concepts as semantic contracts.

## Routing Matrix

- Strategy and critique: chart choice, hierarchy, narrative claim, visual critique, anti-patterns, layout reasoning.
- Declarative grammar: standard tabular charts that fit Vega-Lite, Vega, Observable Plot, or similar grammar.
- D3/SVG: bespoke SVG/DOM geometry, direct labels, axes, annotations, transitions, or crisp vector polish.
- Canvas2D: dense flat marks, frequent redraw, custom hit testing, sparkline tables, or repeated microcharts.
- Three.js/WebGL: GPU-scale marks, particles, flow, shader effects, true 3D, deck.gl, PixiJS, Sigma.js, CesiumJS, luma.gl, or raw WebGL when analytical value justifies it.
- Geospatial: maps, projections, basemaps, thematic layers, slippy/product maps, routes, zoom behavior, or cartographic interaction.
- Dashboards: monitoring, streams, coordinated views, alerting, stale/offline states, and operational workspaces.
- Statistical: distributions, intervals, uncertainty, missingness, aggregation, sampling, and analytical rigor.
- Gantt: project schedules, task spans, milestones, dependencies, baselines, critical path, resources, and PM tool imports/exports.
- Node-link layout: graph auto-layout, crossings, edge routing, overlap, stability, force/layered/tree/radial layouts.
- UML/software architecture: UML, C4, ERD, BPMN, sequence/class/activity/state diagrams, PlantUML, Mermaid, DOT, D2, Structurizr, DBML, XMI/UMLDI.
- Scrollytelling: scroll-driven state, sticky graphics, parallax, moviescrollers, Scrollama, ScrollTrigger, ScrollTimeline, key frames, reduced-motion scenes.
- React/Next.js: component ownership, hydration, client/server boundaries, dynamic loading, route/search-param state, bundle and export integration.
- TypeScript engineering: typed data contracts, reusable APIs, runtime boundaries, renderer adapters, URL codecs, saved-view schemas.
- Testing: unit/component/E2E, visual regression, mocks, dashboard QA, canvas/WebGL readiness, exports, and brittle-test avoidance.
- Accessibility: text alternatives, contrast, redundant encodings, keyboard/screen-reader paths, reduced motion, inclusive review.
- Reports/slides: PDFs, PowerPoint/Google Slides, document embedding, figure packaging, export assets, and regeneration.

When routing is unclear, read `./references/route-by-problem.md` or `./references/prompt-routing-examples.md`. When stack choice is unclear, read `./references/default-stack-selection.md`.

## Quality Gates

- The answer must name the analytical job, chart or artifact family, primary route, and fallback when reasonable alternatives exist.
- Explanatory work needs an insight title, takeaway, artifact mode, annotation plan, source/caveat placement, and mobile reading path.
- Prefer direct labels, embedded keys, small multiples, in-cell graphics, and annotation over detached legends, equal-weight dashboards, or hover-only discovery.
- Use a color-role ledger: neutral context, primary focal accent, optional comparison accent, and separate treatment for selected/focused/alert states. Check contrast, grayscale, and color-deficiency resilience.
- Treat accessibility, mobile, export, URL state, persistence, and QA as design inputs, not cleanup.
- Keep essential values visible without hover. On mobile, replace hover with tap/focus, enlarge hit regions, provide drag/pinch alternatives, and avoid control stacks that hide the main evidence.
- For live or remote data, prefer stale-but-visible views with last-updated, live/stale/offline/partial states, reconnect behavior, and low-bandwidth degradation.
- Prefer declarative grammars before D3, D3/SVG before Canvas when labels/axes dominate, Canvas before WebGL for simple dense flat marks, and WebGL/3D only when scale, picking, shaders, particles, flow, geospatial layers, or depth justify it.
- Motion, particles, generated imagery, domain substrates, and 3D must have a stated analytical purpose plus static/reduced-motion fallback.
- Use editorial hero and background substrates only when they improve orientation, scale, place, mechanism, or label-safe context. Quiet basemaps, terrain, thin cartographic linework, real/generated textures, or clear photographic crops are preferable to generic atmosphere.
- Include an art-direction QA pass for generic AI atmosphere: broad brush strokes, wispy ribbons, bokeh/orbs, one-hue drama, cinematic wallpaper, and background visuals that look polished but do not carry evidence or orientation.
- For sensitive geopolitical, conflict, disaster, displacement, or humanitarian work, use `../../references/foundations/sensitive-geopolitical-and-humanitarian-stories.md`; distinguish measured, estimated, disputed, dated, and schematic layers.
- For fictional or illustrative stories, use `../../references/foundations/fictional-data-story-simulation.md`; require enough deterministic simulated data to support the visual density.
- Treat visual references as principle studies. Transform the idea so the output cannot be mistaken for the reference layout, palette, type system, scene, or pacing.

## Response Contract

- For recommendations: give the primary route, fallback route, chart/artifact family, stack fit, immediate evidence, on-demand details, mobile path, URL/persistence state, accessibility notes, and QA checks.
- For implementation: route to the narrowest specialist skill, then state renderer ownership, coordinate/data encoding, interaction states, fallback/render-ready behavior, instance-count assumption, performance risks, and tests before editing.
- For concept-first visual design: use the shared design workflow, show the required concept set, ask for approval before implementation, then preserve approved concepts as semantic contracts.
- For composite deliverables: state the embedded visualization inventory, specialist owner for each meaningful layer, mini-brief, QA check, and delegated/local fresh-pass status.

## References

- Router references: `./references/route-by-problem.md`, `./references/default-stack-selection.md`, `./references/prompt-routing-examples.md`.
- Core foundations: `../../references/foundations/task-abstraction-and-chart-selection.md`, `../../references/foundations/perception-color-and-encoding.md`, `../../references/foundations/shareable-state-and-persistence.md`, `../../references/foundations/mobile-first-responsive-visualization.md`, `../../references/foundations/layout-hierarchy-and-self-explanatory-ux.md`, `../../references/foundations/implementation-design-and-tradeoffs.md`.
- Advanced workflows: `../../references/foundations/editorial-infographic-system.md`, `../../references/foundations/art-directed-interactive-visual-stories.md`, `../../references/foundations/meaning-preserving-visual-design-workflow.md`, `../../references/foundations/embedded-visualization-self-use.md`, `../../references/foundations/fictional-data-story-simulation.md`, `../../references/foundations/sensitive-geopolitical-and-humanitarian-stories.md`, `../../references/foundations/operational-visualization-workspaces.md`.
- Templates: `../../assets/templates/advanced-interactive-visualization-contract.md`, `../../assets/templates/visual-design-contract.md`, `../../assets/templates/chart-brief.md`, `../../assets/templates/visualization-test-plan.md`.

Referenced files: 4

View saved version →

---
name: gantt-chart-visualization
description: Design, critique, route, and implement Gantt charts and schedule visualizations. Use when the user mentions Gantt charts, project schedules, roadmaps with task spans, milestones, dependencies, predecessors, critical path, baselines, WBS, resource plans, capacity timelines, MS Project, Primavera P6, Jira Advanced Roadmaps, GitHub Projects, Smartsheet, monday.com, Asana, ClickUp, Azure DevOps iterations, or importing/exporting project-management data for a timeline chart.
---

# Gantt Chart Visualization

## Overview

Use this skill when work is organized around time spans, milestones, dependencies, resources, or schedule risk. A Gantt chart is a product surface as much as a chart: it usually combines a task grid, a calendar axis, bars, milestones, dependency links, editing rules, and integration with a project-management source of truth.

Default assumption: recommend a Gantt chart only when the schedule itself is the evidence. If the user mainly needs flow state, task ownership, ranking, issue status, or calendar booking, consider Kanban, tables, milestone timelines, dependency graphs, resource timelines, or uncertainty views first.

Gantt charts are wide by nature. Use `../../references/foundations/mobile-first-responsive-visualization.md` so mobile portrait gets a usable summary or focused slice, and mobile landscape is considered when horizontal schedule inspection matters.

## Core Workflow

1. Classify the scheduling question:
   - planned schedule, actual lifecycle timeline, roadmap, resource plan, capacity view, baseline variance, critical-path review, or stakeholder snapshot
   - whether the user needs read-only explanation, exploratory analysis, or editable project planning
2. Inspect the source before designing:
   - true schedule engine, task tracker, roadmap view, resource calendar, static export, or visual artifact
   - native fields, custom fields, date-only versus datetime values, timezone policy, hierarchy, dependency semantics, calendars, and permissions
   - provenance for every mapped field and any inferred value
3. Normalize into a Gantt model:
   - tasks, hierarchy or WBS, start, end, duration, progress, status, assignee or resource, milestones, dependencies, baselines, calendars, constraints, estimates, actuals, source IDs, and source confidence
4. Decide whether Gantt is the right surface:
   - use Gantt when time spans and dependency or resource reasoning drive the decision
   - use a milestone timeline for executive summaries with few dates
   - use Kanban for workflow state and throughput
   - use a table when lookup and exact fields dominate
   - use a dependency graph when structure matters more than dates
   - use a calendar or resource timeline for booking without project dependencies
   - use uncertainty views when date risk is probabilistic or estimates are still unstable
5. Design the default view:
   - frozen task grid plus calendar axis
   - today marker, visible scale, weekends or non-working time when meaningful
   - clear bars, milestones, dependency links, baselines, progress, and critical-path or risk styling
   - row grouping, hierarchy, and direct labels that work without hover
   - mobile portrait summary or focused default that does not shrink every row into illegibility
   - mobile landscape behavior when wide timeline reading, dependency tracing, or editing is important
6. Define the interaction contract:
   - zoom and pan, row virtualization, expand/collapse, search, filter, sort, hover preview, committed selection, keyboard navigation, drag/resize, dependency editing, undo/redo, export, and deep links
   - touch targets, drag alternatives, keyboard-open search/filter behavior, and settings-return behavior on mobile
7. Choose the renderer and library against real scale:
   - rows, visible time range, dependency count, editability, instance count, export requirements, and source-system sync needs
8. Plan testing and release gates:
   - data adapter tests, date/time fixtures, dependency graph validation, visual states, accessibility, export, and E2E scheduling workflows

## When To Use Gantt

- Project schedules with tasks that have start and finish dates.
- Work breakdown structures, phases, releases, epics, construction schedules, manufacturing plans, implementation plans, launch plans, and migration cutovers.
- Dependency chains where slippage affects downstream work.
- Critical-path, float, baseline, deadline, or variance analysis.
- Resource allocation, capacity planning, or workload conflicts over time.
- Cross-team roadmaps when the question is "what happens when" rather than "what status is this in."
- Schedule imports from MS Project, Primavera P6, Jira Advanced Roadmaps, GitHub Projects, Smartsheet, monday.com, Asana, ClickUp, Azure DevOps, or CSV/XLSX exports.

## When Not To Use Gantt

- Small or highly fluid work where a simple list, table, or Kanban board is clearer.
- Issue queues where status, priority, owner, or SLA matters more than planned span.
- Executive summaries with only releases or launch dates; use a milestone timeline or roadmap.
- Booking, appointments, or shift planning without task dependencies; use a calendar or resource timeline.
- Pure dependency reasoning without reliable dates; use a graph or matrix.
- Probabilistic schedules or early estimates where uncertainty is the main story; use interval, scenario, or risk views.
- Actual lifecycle analysis based only on created, started, and closed timestamps unless the user explicitly asks for actual flow history instead of a planned schedule.

## Stack Selection

- Enterprise editable schedule: use Bryntum Gantt, DHTMLX Gantt, Kendo UI Gantt, Syncfusion Gantt, or a comparable scheduling component when dependency editing, calendars, baselines, critical path, resource views, undo, import/export, and scheduling rules are product requirements.
- Lightweight display or reporting: use Highcharts Gantt, Frappe Gantt, Plotly timelines, Observable Plot, or similar when the view is mostly read-only and the schedule semantics are already computed.
- Resource booking or team availability: use FullCalendar resource timeline or a scheduler-style component when resources and calendar slots matter more than WBS scheduling.
- Small editorial schedule: use D3/SVG or a declarative grammar when labels, annotation, vector export, and precise composition matter.
- Large dense product surface: use a virtualized hybrid layout with HTML for grid text, SVG or Canvas for bars and dependency links, and Canvas for dense bar/link layers when DOM cost dominates.
- Avoid raw WebGL unless mark count, continuous pan/zoom, GPU picking, or custom shader effects make Canvas and DOM impractical.

## Reference Guide

- Read `references/gantt-chart-design-and-use-cases.md` for chart-fit decisions, use cases, and alternatives.
- Read `references/gantt-interaction-patterns.md` for interactive product behavior and editing contracts.
- Read `references/gantt-api-and-export-format-ingestion.md` before mapping MS Project, Primavera, Jira, GitHub Projects, Smartsheet, monday.com, Asana, ClickUp, Azure DevOps, CSV, TSV, XLSX, JSON, PDF, or image exports.
- Read `references/gantt-data-contracts-and-integrations.md` when defining adapters, normalized schemas, source provenance, sync, or product API contracts.
- Read `references/gantt-performance-and-rendering.md` before choosing SVG, Canvas, hybrid rendering, virtualization, or enterprise libraries for large schedules.
- Read `references/gantt-accessibility-export-and-testing.md` for keyboard navigation, screen-reader fallbacks, export, fixtures, and release gates.

## Output Expectations

- State whether Gantt is the primary recommendation or name the better alternative.
- State whether the source is planned schedule data, actual lifecycle data, a roadmap snapshot, a resource calendar, or a static visual artifact.
- Identify which fields are trusted, mapped, inferred, or missing.
- Include the canonical schedule model, minimum interactions, stack choice, performance assumptions, accessibility plan, and export path.
- For external sources, preserve source IDs and call out ambiguous custom fields instead of silently treating them as schedule truth.
- For editable schedules, call out validation and conflict behavior for drag, resize, dependency changes, calendars, baselines, and sync failures.
- For mobile, call out portrait summary or focused slice, landscape support if needed, touch/editing alternatives, keyboard behavior, and offline/stale sync behavior for remote schedules.

## Shared References

- `../../references/foundations/mobile-first-responsive-visualization.md`

## Representative Prompts

- "Should this project data be a Gantt chart, roadmap, Kanban board, or calendar?"
- "Design an interactive Gantt chart for 10,000 construction activities."
- "Map this MS Project XML export into a web Gantt data model."
- "Read a Jira Advanced Roadmaps CSV and decide what fields are safe to show in a timeline."
- "Turn GitHub Projects fields into a release roadmap without inventing dates."
- "Show critical path, dependencies, and baseline variance for this schedule."
- "Choose between DHTMLX, Bryntum, Highcharts Gantt, Frappe Gantt, FullCalendar, D3, and Canvas."
- "Test a Gantt chart with dependency cycles, missing predecessors, timezone edges, and export snapshots."

Referenced files: 7

View saved version →

---
name: geospatial-and-cartographic-visualization
description: Design geospatial and cartographic visualizations. Use when the user needs help deciding whether to use a map, choosing projections or basemaps, building choropleths or symbol maps, or implementing thematic maps, slippy maps, or geospatial interactions with D3 geo, Leaflet, MapLibre, Mapbox GL JS, Google Maps, OpenLayers, deck.gl, ArcGIS Maps SDK, Azure Maps, HERE Maps, CesiumJS, or related tools.
---

# Geospatial and Cartographic Visualization

## Overview

Use this skill when place, projection, movement, or spatial adjacency matter analytically, or when the product surface genuinely needs a map interaction model. Do not use maps by reflex just because there is a latitude, longitude, or region name in the dataset.

Default assumption: use a map only when geography is part of the reasoning or when the product truly needs a map surface. If the task is comparison, ranking, or distribution across regions, a non-map view may be clearer. Distinguish analytical cartography from product-map UX early.

Mobile map users are common and often primary. Use `../../references/foundations/mobile-first-responsive-visualization.md` when choosing marker density, label strategy, portrait/landscape behavior, touch gestures, geolocation/camera/AR capability use, and spotty tile or data connections.

## Working Pattern

1. Decide whether the question is spatial or merely grouped by place.
2. Infer the user's map purpose before asking questions. Recommend a likely substrate and state assumptions, then ask only the missing high-impact questions that would change the map design.
3. Decide which map experience is needed:
   - thematic analytical map
   - slippy map for exploration or layered context
   - route, places, or product-map experience
   - terrain, imagery, or operational situational-awareness map
4. Choose the basemap or substrate intentionally:
   - road and city map for driving, routing, traffic, delivery, road safety, or weather-for-driving
   - topographic or terrain map for hiking, wildfire, flood, landslide, environmental risk, outdoor planning, or field work
   - neutral administrative boundary map for regional comparison when geography matters
   - imagery or raster substrate for satellite, remote sensing, damage, land use, agriculture, construction, or visual evidence
   - quiet neutral basemap for dense points or events unless roads, terrain, or boundaries are part of the reasoning
   - globe or 3D terrain only when depth, terrain, occlusion, or globe context changes the analysis
5. Choose the map family:
   - choropleth
   - symbol map
   - clustered symbol map
   - flow map
   - hex or tile summary
   - raster or density field
   - animated route or trip layer
   - terrain, risk, or damage texture fused to a physical substrate
6. If points overlap, choose the overlap strategy intentionally:
   - clustered summary symbols when dense points need a count or summary preview that can dissolve on zoom
   - displacement or spiderfying when the count is low and each individual point needs immediate visibility
   - exact-location anchor dots when large proportional, halo-style, or concentric point symbols must preserve the true coordinate at detailed zoom levels
7. Choose multiscale zoom behavior intentionally:
   - map-space geometry when the shape, area, or path itself is the thing being inspected
   - screen-stable symbols, labels, and callouts when they act as locators, badges, or UI-like annotations
   - screen-stable strokes for borders, outlines, and graticules unless changing thickness is itself meaningful
   - zoom-stepped sizing only when legibility or hierarchy genuinely improves by changing symbol or label size across scales
8. If dense visible points need one-at-a-time inspection, consider step-through selection with keyboard arrows or previous/next controls within the current extent or current layer.
9. For mobile maps, define the portrait and optional landscape experience before implementation:
   - fewer markers and shorter labels at narrow widths
   - mobile-only marker or label variants when needed
   - a key or detail sheet for labels that cannot fit
   - tap, step-through, search, and reset paths for dense points
   - two-finger zoom or explicit zoom controls when one-finger pan should preserve page scroll
   - stale tile/data, offline, low-bandwidth, and reconnect states
10. For scientific, live, disaster, terrain, climate, seismic, ocean, or other source-sensitive spatial work, create a source and method ledger before visual design or implementation. Include source URL/API, license or attribution, update cadence, units, coordinate reference, coverage gaps, rate limits, cache/fallback policy, and which layers are measured, inferred, schematic, or decorative.
11. Choose a projection, basemap style, and normalization strategy intentionally.
12. For globes or custom projections, audit coordinate alignment across basemap/texture, event markers, labels, hit testing, camera focus, and fallback geometry before coding. Record longitude origin, wrap policy, and at least a few known-place spot checks.
13. Choose the implementation stack:
   - D3 geo for custom projections, thematic cartography, and annotation-rich analytical maps
   - Leaflet for lightweight slippy maps, markers, layer controls, GeoJSON overlays, and familiar pan or zoom controls
   - MapLibre GL JS or Mapbox GL JS for vector-tile styling, data-driven styling, label-aware layer ordering, hillshade, heatmaps, tilt or rotation, and modern slippy-map experiences
   - Google Maps when managed road basemaps, routing, Places, geocoding, traffic context, or Google Maps Platform capabilities drive the product need
   - OpenLayers for GIS-heavy web maps, projections, WMS/WMTS/OGC services, vector and raster layers, and advanced layer control
   - deck.gl for high-volume layers, aggregation, trips, arcs, paths, particle-like flows, point clouds, hex or grid layers, and GPU-heavy geospatial interaction on top of MapLibre, Google Maps, Mapbox, or ArcGIS
   - ArcGIS Maps SDK for hosted GIS services, FeatureLayer workflows, renderers, clustering, binning, heatmaps, editing, and operational maps
   - Azure Maps or HERE Maps for enterprise routing, traffic, fleet, logistics, geocoding, provider data, and vendor-specific location services
   - CesiumJS for 3D globe, terrain, imagery layering, temporal scenes, and 3D Tiles
14. Keep legends, labels, uncertainty, and comparison needs explicit.
15. For editorial map stories, decide whether the map is a quiet stage for evidence, a moving flow field, a particle-guided route story, a risk surface, or a scrollytelling sequence.
16. For conflict, occupation, displacement, disaster, or humanitarian maps, use `../../references/foundations/sensitive-geopolitical-and-humanitarian-stories.md`. Require dated states, source and method notes, attribution, and visible distinctions between measured, estimated, and schematic geometry.
17. If the map owns wheel zoom or gesture panning, also own the browser behavior: prevent page scrolling or scroll chaining, keep reset and button controls visible, and verify the interaction with mouse wheel, trackpad, touch pan, and pinch.
18. Use AR, camera, geolocation, or motion only when they materially improve spatial reasoning or data collection, and always provide manual/non-permission fallbacks.

## Output Expectations

- Explain why a map is or is not justified.
- State the recommended basemap or substrate, required contextual layers, thematic data layers, and any unresolved questions before choosing the implementation stack.
- Call out projection, area, and normalization tradeoffs.
- For live/scientific spatial work, include the source and method ledger plus missing-data/fallback policy.
- For globes/custom projections, include coordinate-frame alignment checks and shortest-path focus behavior when selection moves the camera or globe.
- If large or overlapping point symbols are involved, call out whether the map needs clustered summaries, spiderfying or displacement, exact-location anchor dots, or a combination across zoom levels.
- For interactive maps, state which layers should zoom in map space and which should remain screen-stable.
- For mobile maps, state the portrait layout, whether landscape is justified, marker/label reduction rules, touch gesture ownership, geolocation/camera/AR usage if any, and stale/offline tile or data behavior.
- If users may inspect many nearby points in sequence, call out whether the map needs step-through selection controls in addition to direct clicking.
- Choose the stack based on interaction model, data scale, basemap needs, and annotation requirements.
- For editorial map stories, state the visual substrate, flow or risk layer, annotation plan, motion purpose, and static fallback.
- For animated flow or particle maps, state what each moving mark represents, whether emission rate encodes volume or only direction, and how the same claim appears in reduced-motion and static exports.
- For sensitive geopolitical or humanitarian maps, state the date or update cadence for each map state, the source hierarchy, the evidence status of each layer, and the ethical framing constraints.
- Call out any meaningful dependency on tile providers, commercial map platforms, or style infrastructure.

## References

- Shared theory:
  - `../../references/foundations/task-abstraction-and-chart-selection.md`
  - `../../references/foundations/perception-color-and-encoding.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
  - `../../references/foundations/art-directed-interactive-visual-stories.md`
  - `../../references/foundations/sensitive-geopolitical-and-humanitarian-stories.md`
- Skill references:
  - `./references/map-or-not.md`
  - `./references/adaptive-basemaps-and-layer-stacks.md`
  - `./references/projections-and-normalization.md`
  - `./references/source-method-and-coordinate-ledger.md`
  - `./references/choropleths-symbols-and-flows.md`
  - `./references/point-overlap-strategies.md`
  - `./references/multiscale-symbols-and-zoom-behavior.md`
  - `./references/deckgl-d3-geo-stack-selection.md`
  - `./references/slippy-map-and-product-stack-selection.md`

## Representative Prompts

- "Should this be a map at all?"
- "What basemap and contextual layers should this map use?"
- "Choose the right geospatial visualization for this dataset."
- "Map weather conditions for driving."
- "Visualize wildfire risk near hiking trails."
- "Show flood exposure with terrain and rivers."
- "Help me build a choropleth without misleading normalization."
- "Should this map cluster nearby points, spiderfy them, or show exact-location anchor dots?"
- "How do I keep exact coordinates visible inside large proportional symbols?"
- "What should zoom with the map and what should stay the same size on screen?"
- "When should I use deck.gl instead of D3 geo?"
- "Should this product map use Leaflet, MapLibre, or Google Maps?"
- "Should this use Leaflet, MapLibre, Google Maps, OpenLayers, ArcGIS, deck.gl, or CesiumJS?"
- "Critique this map for cartographic and analytical mistakes."

Referenced files: 10

View saved version →

---
name: grammar-of-graphics-and-declarative-visualization
description: Build data visualizations with declarative grammars. Use when the user needs Vega-Lite, Vega, Observable Plot, or grammar-of-graphics reasoning, especially for tabular charts that do not require bespoke rendering.
---

# Grammar of Graphics and Declarative Visualization

## Overview

Use this skill as the default implementation path for many tabular charts. Declarative grammars are often the fastest, clearest, and most maintainable route when the chart can be expressed as data plus marks plus encodings plus transforms.

This skill covers Vega-Lite, Vega, and Observable Plot. Default to the highest-level tool that cleanly expresses the needed chart and interaction.

## Selection Rules

1. Use Observable Plot for fast exploratory and explanatory charts in JavaScript when concise code is valuable.
2. Use Vega-Lite for portable, declarative specs, multi-view composition, transforms, and embed-friendly chart definitions.
3. Use Vega when the user needs lower-level control that still benefits from a declarative runtime.
4. Leave this skill and route to D3, Canvas, or the Three.js/WebGL skill only when the chart requires bespoke layout, extreme density, GPU-scale rendering, particles, true 3D, or rendering control that the grammar no longer expresses cleanly.

## Working Pattern

1. Normalize the table shape.
2. Name the mark, encodings, transforms, faceting, and interaction model explicitly.
3. Choose the highest-level grammar that supports the chart without contortions.
4. Keep specs readable and portable.
5. Check whether the declarative approach still fits the expected number of simultaneous chart instances on the page.
6. Check mobile portrait and optional landscape behavior: responsive spec, label/tick reduction, hover replacement, touch target policy, and whether the grammar can keep the main visualization visible around controls.
7. Use declarative composition before custom code.

## Output Expectations

- Explain why the chosen grammar fits better than bespoke rendering.
- Keep the spec readable enough to be reused, embedded, or translated across stacks.
- Call out when the declarative path is reaching its limits and a lower-level skill should take over.
- Call out whether the grammar can support the mobile concept contract or whether D3, Canvas, WebGL, or framework-owned layout should take over.
- For new work, include a technical design section covering instance-count assumptions, performance implications, and the maintenance upside of staying declarative.

## References

- Shared theory:
  - `../../references/foundations/task-abstraction-and-chart-selection.md`
  - `../../references/foundations/perception-color-and-encoding.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
  - `../../references/foundations/implementation-design-and-tradeoffs.md`
- Skill references:
  - `./references/vega-lite-and-vega.md`
  - `./references/observable-plot.md`
  - `./references/when-to-stay-declarative.md`

## Representative Prompts

- "Write a Vega-Lite spec for this dataset."
- "Should I use Plot, Vega-Lite, or D3 for this chart?"
- "Build a layered declarative chart with faceting and tooltips."
- "Tell me when this declarative approach stops being a good fit."

Referenced files: 4

View saved version →

---
name: node-link-and-diagram-layout
description: Choose and apply automatic layout strategies for node-link diagrams and connected-node visuals. Use when the user asks how to auto-arrange nodes, reduce line crossings, route edges, avoid overlaps, stabilize layout, or choose graph-layout algorithms for network diagrams, dependency graphs, database schema diagrams, ERDs, state machines, decision trees, flow diagrams, box-and-line editors, or other line-connected nodes.
---

# Node-Link and Diagram Layout

## Overview

Use this skill when the main problem is not which notation to use, but how to place connected nodes so the diagram stays readable. The job is to classify the graph family, choose a layout algorithm that matches the reading task, separate node placement from edge routing and overlap removal, and recommend a stack that can preserve those constraints in production.

Default assumption: the best automatic layout is the one that reinforces the intended reading path with the fewest crossings, bends, overlaps, and surprise placements. Do not treat force-directed layout as a generic answer for all diagrams. Trees, DAGs, port-constrained block diagrams, ERDs, and undirected exploration graphs usually need different algorithms.

For browser-facing node-link views, mobile layout is a graph-reading constraint, not only a CSS breakpoint. Use `../../references/foundations/mobile-first-responsive-visualization.md` when choosing portrait focus views, optional landscape inspection, touch/pan/zoom ownership, and settings placement.

For operational graph workspaces, use `../../references/foundations/operational-visualization-workspaces.md` so layout decisions account for outlines, inspectors, command bars, selected neighborhoods, URL state, mobile panels, and repeated navigation.

## Core Workflow

1. Classify the graph structure before choosing a renderer:
   - rooted tree or forest
   - directed acyclic graph
   - cyclic directed graph with a dominant flow
   - general undirected graph
   - radial or hub-and-spoke structure
   - clustered or compound graph
   - port-constrained block diagram
   - table-like schema or ERD
   - nearly planar topology where crossing count dominates readability
2. Identify the primary reading task:
   - parent-child depth
   - top-to-bottom or left-to-right flow
   - reachability and dependency tracing
   - cluster discovery
   - cycle inspection
   - shortest path or neighborhood exploration
   - table relationship tracing
   - stable editing with minimal layout drift
3. Record geometry constraints up front:
   - real node widths and heights, not point nodes
   - labels that must fit without scaling below readability
   - ports, handles, side constraints, or fixed connection order
   - nested groups, lanes, clusters, or compounds
   - whether some nodes are pinned or semi-pinned
4. Choose the layout family that matches the structure:
   - tidy tree layout for rooted ordered trees and decision trees
   - layered or Sugiyama-style layout for directional processes, state machines, dependency maps, class hierarchies, ERDs, and most UML-like flow diagrams
   - stress majorization or force-directed layout for undirected relational exploration where cluster shape matters more than global direction
   - radial or concentric layout when distance from a root is the main story
   - circular layout when cycle structure is the evidence
   - planarization-driven layout when the graph is non-planar but low crossing count is the main objective
5. Choose edge routing separately from node placement:
   - straight or polyline when the graph is sparse and directional flow is already clear
   - orthogonal when tables, ports, block diagrams, lanes, or circuit-like reading dominate
   - spline routing when static aesthetics matter more than precise traceability and there is enough whitespace
6. Treat overlap removal, label placement, and packing as explicit phases:
   - remove node overlap after layout if the engine starts from point nodes
   - reserve gutters for connector-dense tables and schemas
   - keep edge labels out of node bodies and above selected paths
   - pack connected components only after the component layouts are individually legible
7. Prefer stability when users will edit, compare revisions, or recognize repeated diagrams:
   - preserve node order when the source model has meaningful order
   - preserve port order when connectors are semantically ordered
   - use interactive or constraint-aware layered modes instead of re-randomizing
8. Validate the result with readability criteria instead of trusting the engine:
   - crossings are low enough for the task
   - bends are limited and meaningful
   - nodes and labels do not overlap
   - directionality is obvious
   - edge tracing is possible without visual hunting
   - the layout stays readable on narrow widths or falls back to scrolling, filtering, or faceting
   - mobile portrait starts on the most important region instead of shrinking the entire graph
   - mobile landscape is offered when a wide graph, timeline, or schema materially improves tracing
   - operational shells keep filters, outline trees, selected nodes, and inspectors synchronized without stealing space from the graph

## Algorithm Defaults

- Rooted ordered trees and decision trees:
  - Prefer Reingold-Tilford style tidy trees and Buchheim's linear-time refinement.
  - Use radial tree variants only when depth from a root matters more than label density.
  - Do not use generic force layout for decision trees unless the tree metaphor itself is intentionally abandoned.
- State machines, dependency graphs, workflow diagrams, class hierarchies, ERDs, and most UML-like directional diagrams:
  - Prefer layered layout derived from Sugiyama.
  - Use cycle breaking, layer assignment, crossing minimization, node placement, and edge routing as separate concerns.
  - For table schemas, state diagrams, and block diagrams with connector semantics, prefer port-aware layered layout with orthogonal routing.
- General undirected networks:
  - Prefer stress majorization or force-directed placement when cluster shape, neighborhood, or approximate graph distance is the point.
  - Prefer multilevel force methods for larger graphs.
  - Avoid force layout when users need strict rank order, deterministic business flow, or table-like schemas.
- Large topology where the graph is dense and not meaningfully hierarchical:
  - Use multilevel force approaches, filtering, clustering, matrix fallbacks, or multiple coordinated views before cramming everything into one node-link view.
- Nearly planar but non-planar graphs:
  - Consider planarization pipelines when crossing count matters more than preserving a strict hierarchy.
  - Treat this as an advanced fallback, not a default for ordinary UML-like diagrams.

## Stack Defaults

- Graphviz `dot`: best default for static layered layouts in documentation or build-time generation.
- Graphviz `neato`: good default for modest undirected graphs when stress majorization is appropriate.
- Graphviz `fdp` and `sfdp`: good for force-directed and multilevel force layouts, especially for larger undirected networks.
- Graphviz `twopi` and `circo`: use when radial or circular structure is truly the reading model.
- ELK Layered: best default for interactive products that need layered layout with ports, compounds, labels, orthogonal routing, or layout constraints.
- React Flow plus ELK or Dagre: good for node editors when React owns the interaction layer and the actual layout engine remains external.
- Cytoscape.js: good when graph analysis, graph algorithms, and multiple layout modes matter as much as the rendering.
- Bespoke SVG, Canvas, or WebGL: use only when the visual composition or scale requires it after the algorithm family is already decided.

## Anti-Patterns

- Using force-directed layout for ERDs, state machines, or business workflows that have a clear direction.
- Treating overlap removal as a substitute for choosing the right layout family.
- Ignoring real node dimensions and then trying to fix collisions at the end.
- Letting connectors run under schema tables, lane headers, or large node labels.
- Relying on a single dense node-link view when a matrix, tree, outline, focus view, or filtered subgraph would explain the structure better.
- Re-running unstable layout from scratch after every small edit in an interactive tool.
- Shrinking text below readable size instead of using an intrinsic canvas and scrollable viewport.
- Letting mobile controls or legends appear before the graph while the actual topology starts below the fold.
- Requiring pixel-perfect taps on dense nodes without search, step-through, or enlarged hit regions.

## Reference Guide

- Read `references/algorithm-selection.md` first for graph-family to algorithm-family mapping.
- Read `references/layered-tree-force-and-radial-layouts.md` when choosing among tree, layered, force, radial, circular, and multilevel approaches.
- Read `references/routing-overlap-and-quality.md` for orthogonal routing, planarization, overlap removal, port constraints, and readability criteria.

## Output Expectations

- State the graph family and why it was classified that way.
- State the recommended layout family and one fallback.
- State the routing style, overlap strategy, and stability strategy.
- Call out whether ports, order constraints, fixed nodes, or compounds require a layout engine with stronger constraint support.
- For product work, recommend a concrete stack and make clear which part owns semantics, layout, and rendering.
- If the graph is too dense for a clean node-link view, say so and recommend filtering, faceting, clustering, matrix views, or overview-plus-detail.
- For mobile, state the portrait focus strategy, landscape need if any, touch target/hit-area policy, search or step-through path, and pan/zoom/browser gesture ownership.
- For operational graph workspaces, state the shell, default selected or focused neighborhood, outline/inspector synchronization, URL state, and empty-surface clear-selection behavior.
- If the problem is really notation selection, route to the UML or strategy skill instead of over-solving layout alone.

## Adjacent Skills

- `../data-visualization/SKILL.md`
- `../uml-and-software-architecture-visualization/SKILL.md`
- `../typescript-data-visualization-engineering/SKILL.md`
- `../react-and-nextjs-data-visualization/SKILL.md`
- `../d3-data-visualization/SKILL.md`
- `../canvas2d-data-visualization/SKILL.md`
- `../threejs-data-visualization/SKILL.md`
- `../testing-data-visualizations/SKILL.md`
- `../../references/foundations/mobile-first-responsive-visualization.md`
- `../../references/foundations/operational-visualization-workspaces.md`

## Representative Prompts

- "How should I auto-arrange this network diagram so the lines stop crossing so much?"
- "What layout algorithm should I use for a database schema diagram?"
- "Choose between ELK, Graphviz, Dagre, force layout, and a custom approach for this state machine."
- "Make this dependency graph readable without overlapping boxes and labels."
- "How do I route edges for an ERD so foreign keys do not run under the tables?"
- "What should I use for a decision tree, a DAG, and an undirected network?"
- "We need stable auto-layout in a React node editor."

Referenced files: 4

View saved version →

---
name: react-and-nextjs-data-visualization
description: Integrate data visualizations into React and Next.js applications. Use when the user needs chart components, UML-like or architecture diagram components, React integration patterns, Next.js client or server boundaries, hydration-safe rendering, lazy loading, framework-aware performance, scroll-driven visual stories, or export guidance.
---

# React and Next.js Data Visualization

## Overview

Use this skill when the visualization lives inside a React or Next.js product surface. The focus is not just chart rendering. The focus is component ownership, hydration safety, client and server boundaries, bundle strategy, and clean integration between React and whichever visualization layer is actually drawing the marks.

Default assumption: React should own structure, layout, and application state, while the visualization layer owns scales, geometry, and narrowly scoped imperative rendering.

If the main request is about screenshot testing, visual regression, mocked chart data, or E2E coverage strategy, route first to `../testing-data-visualizations/SKILL.md` and pair back to this skill only for React- or Next-specific implementation details.

## Choose This Skill When

- the user is building charts inside React components
- the app is using Next.js, the App Router, or server and client component boundaries
- the chart uses D3, Canvas, SVG, Vega-Lite, Plot, WebGL, deck.gl, PixiJS, Sigma.js, or Three.js inside a React surface
- the surface uses Mermaid, React Flow, Cytoscape.js, Sprotty, JointJS, GoJS, ELK, Dagre, Graphviz/WASM, D2, or another UML-like diagram renderer
- hydration, SSR, dynamic loading, or browser-only APIs affect the implementation
- bundle size, route-level loading, and product integration matter
- the page is an editorial visual story that combines React layout, scroll states, parallax, sticky graphics, generated assets, SVG/Canvas/D3/WebGL/Three.js layers, particles, flow animation, and accessibility fallbacks

## Working Pattern

1. Decide which parts are server-safe and which must run in the browser.
2. Keep data loading, transformation, chart configuration, and render-layer concerns separated.
3. Estimate how many chart instances can be visible on a page at once and whether expensive work can be shared across them.
4. Let React own layout, controls, routing state, persistence affordances, and active-state summaries.
5. Let D3, Canvas, Vega-Lite embeds, Plot, WebGL libraries, or Three.js own the mark-level rendering.
6. Model URL-backed view state explicitly before wiring controls: filters, range, metric, comparison, selected entity, active tab, map bounds, zoom, camera target, and drill-down path.
7. Use localStorage only for tiny personal preferences; use IndexedDB or remote storage for larger saved views, drafts, cached slices, custom annotations, or shared/cross-device workspaces. Incoming URL state should override persisted defaults.
8. Use dynamic loading or client-only boundaries intentionally for browser-only visualization code.
9. If the chart owns wheel, pinch, or drag interactions, make the browser contract explicit. Use a non-passive native listener or library hook when default scrolling must be canceled, and do not assume framework-level `onWheel` is enough.
10. For editorial or infographic surfaces, keep the insight title, artifact mode, subtitle, annotation plan, source note, large-screen layout, mobile portrait layout, optional mobile landscape layout, and chart render layer as explicit component responsibilities. Use `../../references/foundations/mobile-first-responsive-visualization.md` for touch, keyboard, visual viewport, spotty-connection, and device-capability decisions.
11. For scrollytelling or parallax, use `../scrollytelling-and-parallax-data-visualization/SKILL.md` for the story contract. Model scenes as typed state rather than ad hoc scroll math. Each scene should define visible layers, annotation text, media assets, camera or transform state, trigger/progress range, static key frame, and reduced-motion fallback.
12. For advanced editorial, report, deck, generated-image, animation, or existing-page integration work, use `../../references/foundations/meaning-preserving-visual-design-workflow.md` and `../../references/foundations/mobile-first-responsive-visualization.md` before implementation. Apply the shared workflow for concept images, large-screen/mobile variants, approval or iteration, and the binding semantic design contract React must implement.
13. For generated imagery or illustration, keep assets in deterministic public paths or importable modules, and keep labels/data overlays in React-owned, editable layers.
14. For WebGL, keep renderer lifecycle, resize, context loss, disposal, and animation loops inside a narrow client-only component boundary. React should pass data versions and props, not mutate GPU objects throughout the tree.
15. For interactive UML, ERD, dependency, state machine, flow, or architecture diagrams, use `../uml-and-software-architecture-visualization/SKILL.md` first; React should own app state, panels, controls, routing, and persistence while the diagram layer owns layout/rendering details.
16. For operational workspaces, use `../../references/foundations/operational-visualization-workspaces.md` before component decomposition. React should own shell state, command bars, drawers, rails, active summaries, URL state, and inspector synchronization while the visualization layer owns geometry, layout, and picking.

## Next.js Guidance

- Prefer Server Components for data fetching, framing content, and layout when the chart does not need browser APIs there.
- Use Client Components for interactive charts, measuring containers, pointer events, or browser-only libraries.
- Use dynamic imports when the charting runtime is not needed on the initial path or should avoid SSR.
- Keep chart assets and export paths deterministic when the same visualization must appear in reports or documents.
- Use route params or search params as the canonical input for shareable view state when possible. Parse and normalize them before initializing client-only chart state so linked views do not flicker through unrelated defaults.
- Use replace-style navigation for high-frequency transient changes and push-style navigation for committed selections, applied filters, drill-down steps, and saved-view transitions.
- For publication-style pages, design desktop and mobile compositions as sibling states, not as a single squeezed SVG.
- On mobile, keep the main visualization first or immediately available. Put secondary filters, inspectors, and settings in collapsible panels, drawers, bottom sheets, or inline controls that preserve active-state summaries and return focus/scroll to the chart after Apply, Cancel, Reset, or close.
- For dense workspaces, prefer a desktop outline/control rail, central viewport, and inspector rail; use a mobile command bar with outline, filter, and details panels instead of stacking the desktop rails above the visualization.
- Use `window.visualViewport` or equivalent resize handling for keyboard-heavy controls so search, filter, and annotation flows do not hide the only critical action or permanently obscure the visualization.
- Use Pointer Events for custom touch/pen/mouse interactions when possible, with explicit `touch-action`, enlarged hit areas, drag alternatives, reset controls, and no hover-only evidence.
- Use IntersectionObserver, Scrollama, Motion `useScroll`, GSAP ScrollTrigger, CSS scroll timelines, or explicit step controls sparingly and accessibly. The default view should still communicate the claim.
- Prefer native scroll and `position: sticky` for pinned story sections. Avoid scrolljacking and keep wheel, touch, scrollbar, and keyboard behavior predictable.
- Use `prefers-reduced-motion` to switch animated stories to final-state, key-frame, or stepped layouts.
- Lazy-load heavy WebGL, 3D, video, or image-generation-derived assets without causing layout shift. Reserve aspect ratios and label lanes.
- Pause WebGL animation loops when offscreen, route-hidden, tabbed away, or reduced-motion is active.

## Output Expectations

- Name the ownership boundary between React and the visualization layer.
- For explanatory work, name the insight title, artifact mode, annotation layer, direct-label strategy, and mobile reading path.
- For mobile work, name the mobile portrait layout, whether landscape is supported, how controls avoid covering the chart, how the on-screen keyboard behaves, and how touch/pinch interactions map to selection, zoom, pan, and reset.
- For operational workspaces, name the shell components, default selected state, synchronized outline/search/filter/inspector behavior, empty-surface clear-selection rule, mobile command panels, and URL-backed workspace state.
- For art-directed work, name generated or illustrated assets, scroll/animation states, reduced-motion behavior, and still-frame fallback.
- For concepted surfaces, use the shared design workflow for concept images, approval status, approved references, binding semantic design contract, locked and flexible elements, React-owned data layers, renderer-owned layers, mobile/landscape continuation, and approved deviations.
- For scrollytelling or parallax, name the scroll controller, scene contract, trigger/progress ranges, sticky layout, mobile fallback, and static key frames.
- For WebGL or particles, name the renderer, data-to-buffer boundary, animation clock, cleanup/disposal path, reduced-motion behavior, and static fallback.
- Call out any client-only or hydration-sensitive code explicitly.
- Call out any interaction that must suppress native browser scrolling or scroll chaining.
- Call out which state is URL-backed, locally persisted, IndexedDB-backed, remote-saved, or intentionally ephemeral.
- Call out copy-link, saved-view, reset, refresh, back/forward, and invalid URL-state behavior.
- Call out which control or detail areas are collapsed by default or closable, and how active state remains visible.
- Call out live-data connection behavior on mobile: stale state, reconnect, offline/partial data, lower-bandwidth mode, and alerting/notification strategy when relevant.
- State whether the chart is a good fit for SSR, client-only rendering, or dynamic loading.
- For new work, include a technical design section covering simultaneous instance count, per-instance versus page-level performance, and maintenance implications of the chosen integration pattern.
- Keep bundle size, export needs, and accessibility visible in the design.

## References

- Shared theory:
  - `../../references/foundations/editorial-infographic-system.md`
  - `../../references/foundations/art-directed-interactive-visual-stories.md`
  - `../../references/foundations/meaning-preserving-visual-design-workflow.md`
  - `../../references/foundations/task-abstraction-and-chart-selection.md`
  - `../../references/foundations/perception-color-and-encoding.md`
  - `../../references/foundations/shareable-state-and-persistence.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
  - `../../references/foundations/operational-visualization-workspaces.md`
  - `../../references/foundations/implementation-design-and-tradeoffs.md`
- Skill references:
  - `./references/react-component-patterns.md`
  - `./references/d3-canvas-and-grammar-in-react.md`
  - `./references/nextjs-client-server-boundaries.md`
  - `./references/lazy-loading-ssr-and-bundle-strategy.md`
  - `../uml-and-software-architecture-visualization/SKILL.md`
  - `../scrollytelling-and-parallax-data-visualization/SKILL.md`
  - `../testing-data-visualizations/SKILL.md`

## Representative Prompts

- "How should I integrate this chart into a React app?"
- "What is the right React pattern for D3, Canvas, or Vega-Lite here?"
- "Make this visualization work cleanly in Next.js App Router."
- "Build a React scrollytelling story with sticky graphics and reduced-motion fallback."
- "Should this chart be a Client Component or use dynamic import?"
- "Help me avoid hydration and SSR issues with this visualization."
- "Build an interactive React UML, ERD, flow, state machine, dependency, or architecture diagram."

Referenced files: 5

View saved version →

---
name: reports-pdfs-and-slide-automation
description: Lay out and export data-rich reports and documents. Use when the user needs report structure, figure packaging, PDFs, PowerPoint or Google Slides automation, or programmatic insertion of visualizations, UML-like diagrams, or architecture diagrams into documents.
---

# Reports, PDFs, and Slide Automation

## Overview

Use this skill when the output is a deliverable rather than a standalone chart. That includes reports, briefing decks, PDFs, slide exports, document embeds, and reusable figure assets that other systems can place into files.

Default assumption: build figures as durable assets first, then compose them into documents. Do not rely on screenshots unless the workflow truly has no better option.

For editorial reports and infographic packages, use `../../references/foundations/editorial-infographic-system.md` before layout. For visual stories that include animation, generated imagery, illustrated substrates, WebGL, particles, 3D, or scrollytelling, also use `../../references/foundations/art-directed-interactive-visual-stories.md`. When page, slide, or figure composition materially affects interpretation, use `../../references/foundations/meaning-preserving-visual-design-workflow.md` and `../../references/foundations/mobile-first-responsive-visualization.md` for concept generation, user approval, mobile variants, and semantic design contracts. The deliverable should read as a sequence of claims supported by figures, not as a dashboard export.

For reports, decks, PDFs, and documents with multiple meaningful figures, use `../../references/foundations/embedded-visualization-self-use.md` before page or slide composition. Each chart, map, table-graphic, inset, flow layer, static fallback, and export-only frame needs a specialist owner and mini-brief before it becomes a placed asset.

## Common Targets

- HTML reports
- PDF reports generated from HTML or direct PDF libraries
- PowerPoint decks
- Google Slides decks
- Word or Docs-style narrative documents
- Markdown and static-site reports
- Technical documentation with UML, ERD, C4, BPMN, flow, state machine, dependency, schema, or architecture diagram assets

## Figure Packaging Rules

1. Inventory every meaningful embedded figure or visual layer before layout, assign a primary specialist owner, and write a mini-brief covering job, data shape, encoding, interaction or static fallback, accessibility, QA, and fresh-pass status.
2. Use an authorized delegated specialist or explicit local specialist pass for substantial figures before composition. The report or deck owner integrates the results, keeps shared encodings consistent, and performs final editorial QA.
3. For advanced report, deck, or page compositions, create a visual design contract before implementation, but only after the user approves the generated layout concept set or requests a revised concept. Do not make project changes, finalize assets, or generate implementation code while approval is pending. If the user requests changes, revise or regenerate the concept set and repeat the concise bullet review until the user agrees on the design. The contract should map the approved concepts to figure slots, locked layout elements, flexible production details, data-bound layers, source/caveat placement, export frames, mobile/landscape or print adaptations, and approved deviations.
4. Export each figure in the format the medium needs:
   - SVG for vector and print
   - PNG for slides and office documents
   - PDF when downstream systems preserve vector PDF pages well
5. Keep chart dimensions intentional for page or slide slots.
6. Preserve consistent theming, typography, and color semantics across all assets.
7. Keep annotations readable at final output size.
8. Include source, caveat, and alternative text metadata with each exported figure.
9. For animated or interactive stories, export first frame, key frames, and final frame so the argument survives in PDF, slides, and reduced-motion contexts.
10. For WebGL or particle scenes, export a static fallback that preserves the data claim: final frame, key frames, arrows, path widths, selected focus state, or a panel sequence.
11. For generated imagery, keep image assets, data overlays, captions, and source notes as separate layers whenever the target medium permits.
12. For UML-like, ERD, C4, BPMN, flow, dependency, or architecture diagrams, use `../uml-and-software-architecture-visualization/SKILL.md` first and export both the diagram source and the rendered asset when the target workflow permits.

## Programmatic PDF Approaches

- Browser or HTML-first:
   - render semantic HTML and CSS
   - print with Playwright or Puppeteer
- JavaScript-first:
   - pdf-lib for PDF manipulation
   - PDFKit or jsPDF for direct generation

For Codex-driven workflows, the most reliable pattern is often: generate charts as SVG or PNG, compose an HTML report, then render to PDF with a browser engine.

## Slide Deck Approaches

- PowerPoint:
   - `pptxgenjs` in JavaScript or TypeScript
- Google Slides:
   - generate assets first
   - place them via the Google Slides API with explicit page geometry

## Document Embedding Patterns

- Word or DOCX: insert exported PNG or SVG where supported and keep captions separate from the image raster.
- Markdown or static docs: prefer SVG for crisp web rendering.
- PDFs: either compose from exported assets or print from HTML layouts.
- Spreadsheets and office docs: use fixed-aspect PNG exports when office rendering of SVG is inconsistent.

## Report Layout Principles

- Start with the question, not the chart inventory.
- Lead with the strongest claim and the view that supports it.
- Use supporting small multiples instead of giant dashboard mosaics.
- Integrate explanatory text near the figure it explains.
- Use insight titles, direct labels, and annotations in the figure asset itself so it survives being moved into slides, PDFs, or article embeds.
- When an interactive story has to become static, package it as a paced panel sequence instead of a single unexplained screenshot.
- Reserve appendix sections for dense tables and methodological detail.

## Output Expectations

- Name the target medium.
- Provide the embedded visualization inventory with specialist owners, mini-brief summaries, QA checks, and delegated or local fresh-pass status.
- For concepted report, deck, or page layouts, use the shared design workflow for required concept images, approval status, approved references, binding visual design contract, locked and flexible elements, data-bound layers, mobile/landscape or print continuation, approved deviations, and semantic fidelity QA.
- Define the export asset set.
- Make page or slide layout explicit.
- For art-directed visual stories, identify which key frames, generated assets, and data overlays should be exported.
- Preserve a clean path for regeneration when the data changes.

## References

- Shared theory:
  - `../../references/foundations/editorial-infographic-system.md`
  - `../../references/foundations/art-directed-interactive-visual-stories.md`
  - `../../references/foundations/meaning-preserving-visual-design-workflow.md`
  - `../../references/foundations/embedded-visualization-self-use.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
  - `../../references/foundations/storytelling-annotation-and-critique.md`
- Skill references:
  - `./references/report-structure-and-figure-packaging.md`
  - `./references/pdf-generation-paths.md`
  - `./references/powerpoint-and-google-slides.md`
  - `./references/document-embedding-and-regeneration.md`
  - `../uml-and-software-architecture-visualization/SKILL.md`

## Representative Prompts

- "Turn this dashboard into an executive PDF report."
- "Generate a PowerPoint deck with chart assets and commentary."
- "Programmatically add these visualizations to a report."
- "Create an HTML report and render it to PDF with Playwright."
- "Automate Google Slides or PowerPoint creation from chart assets."
- "Package UML, ERD, C4, BPMN, flow, state machine, dependency, or architecture diagrams into a report, PDF, or deck."

Referenced files: 5

View saved version →

---
name: scrollytelling-and-parallax-data-visualization
description: Design and implement parallax scrolling and scrollytelling data visualizations. Use when the user asks for parallax scrolling, scrollytelling, scroll-driven timelines, sticky graphics, Scrollama, ScrollTrigger, ScrollTimeline, view timelines, rich-media timelines, moviescrollers, scroll-scrubbed charts, staged narrative reveals, or interactive visual stories where scrolling changes a data visualization or media scene.
---

# Scrollytelling and Parallax Data Visualization

## Overview

Use this skill when scrolling is part of the explanation, not just navigation. Scrollytelling is an author-led narrative structure in which text, data marks, imagery, video, maps, or camera states change as the reader scrolls. Parallax is one possible scrollytelling technique: layers move at different rates to create depth, reveal scale, or connect foreground evidence to background context.

Default assumption: preserve native scrolling and make every scene meaningful as a still. Do not use parallax or scroll-scrubbed motion as decoration. Use it only when staged reveal, state change, elapsed time, spatial movement, or rich-media synchronization materially reduces interpretation cost.

## When To Use It

- A timeline, map, chart, 3D scene, video, or illustrated substrate needs staged reveal while the reader scrolls.
- The story benefits from a linear author-led path before optional reader exploration.
- A sticky graphic, side-by-side text/visual layout, overlay text on media, or scroll-scrubbed transition is being planned or implemented.
- The user mentions Scrollama, GSAP ScrollTrigger, Motion `useScroll`, CSS `ScrollTimeline`, ViewTimeline, IntersectionObserver, `position: sticky`, parallax layers, moviescroller, or scroll-driven animation.

Avoid scrollytelling when the story is clearer as a static chart, direct-label small multiples, a conventional article with inline figures, or an explicit stepper. Prefer a stepper when the states are discrete and the reader needs direct access, known length, replay, or controlled comparison more than continuous scroll.

## Working Pattern

1. Define the story contract:
   - one-sentence takeaway
   - author-led sequence and any reader-controlled exploration
   - why scrolling is necessary
   - what the first frame, each key frame, and final frame prove
2. For fictional, synthetic, or illustrative stories, require a data-rich simulation before storyboarding. Use `../../references/foundations/fictional-data-story-simulation.md` to define entity, temporal, spatial or physical, event, outcome, and derived comparison layers.
3. For art-directed, image-supported, composite, or existing-page scrollytelling work, use `../../references/foundations/meaning-preserving-visual-design-workflow.md` and `../../references/foundations/mobile-first-responsive-visualization.md`. Apply those shared references for Codex concept generation, large-screen/mobile variants, approval or iteration, scene contracts, and implementation deferral.
4. Choose the scrollytelling technique:
   - graphic sequence
   - animated transition
   - pan and zoom
   - moviescroller
   - show-and-play
   - parallax depth layer
   - sticky side-by-side or overlay
   - stacked mobile fallback or mobile-specific stepper
5. Model scenes as data, not ad hoc scroll math. Each scene declares text, visual state, data layer, media asset, annotation, scroll trigger or progress range, reduced-motion fallback, static key frame, embedded visualization skill owner, visual-density role, interactive discovery affordance, asset-continuity requirement, scroll-controlled media behavior, and any approved concept/key-frame contract. Approved key-frame concepts are binding scene contracts: the implementation must preserve their evidence hierarchy, staging, label-safe regions, interaction meaning, and static fallback unless a deviation is approved or recorded as meaning-preserving.
6. For each embedded visual layer, use `../../references/foundations/embedded-visualization-self-use.md` to name the primary specialist owner and mini-brief the layer's job, data shape, encoding, interaction, fallback, accessibility, QA check, and delegated or local fresh-pass status before scene composition.
7. Require every scene to include at least one evidence-bearing visual change: chart transition, map or layer reveal, annotation shift, camera move, particle or flow state, video frame or state, or interactive hotspot. If the scene only adds drama, simplify or add real evidence.
8. Pick the lightest implementation:
   - native scroll and `position: sticky` for pinning
   - IntersectionObserver or Scrollama for step triggers
   - CSS scroll-driven animations for simple transform or opacity when support and fallback are acceptable
   - Motion or GSAP ScrollTrigger for complex React choreography, scrubbing, pinning, snapping, or timeline labels
   - D3/SVG, Canvas2D, WebGL, deck.gl, PixiJS, Three.js, or video only when the visual layer requires it
9. Protect the browser contract:
   - do not scrolljack
   - keep feedback immediate, reversible, and interruptible
   - preserve standard wheel, touch, scrollbar, and keyboard behavior
   - avoid surprise autoplay, especially audio
   - account for mobile browser chrome, changing viewport height, touch momentum, and keyboard-open states
10. Build accessibility and fallbacks before polish:
   - honor `prefers-reduced-motion`
   - provide static key frames, a stacked version, or a stepped fallback
   - keep focus order and reading order coherent
   - ensure the main claim survives screenshots and static export
11. Test performance and interpretation:
   - profile scroll jank on desktop and mobile
   - verify no layout thrashing or layout-triggering animation
   - reserve media dimensions and lazy-load offscreen assets
   - test fast scroll, reverse scroll, resize, reduced motion, keyboard navigation, and mobile browser chrome changes

## Routing

- Use `../visualization-strategy-and-critique/SKILL.md` first when deciding whether the story should be scrollytelling, a stepper, small multiples, or a static editorial chart.
- Use `../react-and-nextjs-data-visualization/SKILL.md` when the implementation is a React or Next.js story surface, especially with hydration, client-only libraries, dynamic imports, or route-level asset loading.
- Use `../d3-data-visualization/SKILL.md` when SVG data marks, labels, annotations, and scene-state transitions are the core work.
- Use `../canvas2d-data-visualization/SKILL.md` when dense flat marks or custom hit testing make SVG too heavy.
- Use `../threejs-data-visualization/SKILL.md` when WebGL, GPU layers, particles, flow, or camera-led 3D are necessary.
- Use `../geospatial-and-cartographic-visualization/SKILL.md` for map scrollytelling, fly-to sequences, route stories, or pan/zoom geography.
- Use `../accessibility-and-inclusive-visualization/SKILL.md` when motion sensitivity, keyboard path, screen-reader alternatives, or static fallbacks are central.
- Use `../testing-data-visualizations/SKILL.md` when validating scroll states, visual regression, render readiness, media loading, or reduced-motion behavior.
- Use `../../references/foundations/fictional-data-story-simulation.md` when sparse invented data would otherwise force the scroll story to rely on walls of text, decorative parallax, or generic chart tiles.

## Output Expectations

- State whether scrollytelling is justified and what would be lost in a simpler format.
- Name the scrollytelling technique and the reader's path through scenes.
- Provide a scene contract with trigger/progress ranges and static fallbacks.
- For Codex image-generated layout or key-frame concepts, use the shared design workflow for concept images, approval status, approved references, binding semantic design contract, locked and flexible elements, data-bound layers, mobile/landscape continuation, approved deviations, and concept-to-result fidelity checks.
- For every embedded visual layer, provide the specialist owner, mini-brief summary, QA check, and whether delegated fresh context, a local fresh specialist pass, or a lightweight exception was used.
- For fictional stories, provide the simulated-world data richness contract and the specialist mini-brief for every embedded visualization layer.
- Name the implementation stack and why it is the lightest reliable option.
- Call out browser behavior explicitly: native scroll, sticky pinning, event listeners, scroll ownership, and keyboard behavior.
- State reduced-motion behavior, mobile portrait path, optional landscape path, media loading plan, spotty-connection behavior, and performance risks.
- Include the first-frame, key-frame, final-frame, and screenshot acceptance criteria.

## References

- `./references/story-patterns-and-scene-contracts.md`
- `./references/implementation-and-performance.md`
- `./references/accessibility-testing-and-review.md`
- `../../references/foundations/meaning-preserving-visual-design-workflow.md`
- `../../references/foundations/embedded-visualization-self-use.md`
- `../../references/foundations/mobile-first-responsive-visualization.md`

## Representative Prompts

- "Make a parallax scrolling timeline with maps and video."
- "Use Scrollama for a data story."
- "Should this be scrollytelling or a stepper?"
- "Design a scroll-driven visualization that is accessible and performant."
- "Build a sticky graphic story where the chart changes as the reader scrolls."
- "Storyboard a moviescroller that advances video frames with scroll progress."

Referenced files: 4

View saved version →

---
name: statistical-and-uncertainty-visualization
description: Design statistically honest and uncertainty-aware visualizations. Use when the user needs help showing distributions, intervals, confidence, missingness, sampling effects, or analytical rigor in charts and dashboards.
---

# Statistical and Uncertainty Visualization

## Overview

Use this skill when the risk is analytical distortion rather than rendering difficulty. This skill focuses on distributions, intervals, uncertainty, missingness, aggregation effects, and common statistical storytelling failures.

Default assumption: if a claim depends on variability, estimation, sampling, or model uncertainty, the visualization should show that explicitly.

## Working Pattern

1. Identify whether the viewer needs exact values, distributions, intervals, or model-derived estimates.
2. Choose encodings that show spread, uncertainty, missingness, or sample size honestly.
3. Avoid summarizing away the variation that matters to the decision.
4. Pair concise explanations with the view when the uncertainty concept is nontrivial.

## Output Expectations

- Name the statistical question, not just the chart type.
- Explain why the chosen encoding is more truthful than the tempting alternative.
- Call out when aggregation, smoothing, or interval choice can mislead.

## References

- Shared theory:
  - `../../references/foundations/task-abstraction-and-chart-selection.md`
  - `../../references/foundations/perception-color-and-encoding.md`
- Skill references:
  - `./references/distribution-and-summary-choices.md`
  - `./references/uncertainty-encodings.md`
  - `./references/experimental-and-analytical-pitfalls.md`
  - `./references/missingness-and-confidence.md`

## Representative Prompts

- "What chart should I use to show uncertainty here?"
- "Should this be a histogram, box plot, violin plot, or density plot?"
- "How do I show confidence intervals without misleading people?"
- "This dashboard hides variability. How should I fix it?"
- "Help me visualize missing data and sample size honestly."

Referenced files: 5

View saved version →

---
name: testing-data-visualizations
description: Test data visualizations and dashboards. Use when the user needs chart or diagram test strategy, screenshot or image diff testing, visual regression, mocked or synthetic chart data, component or unit tests, E2E dashboard QA, interactive UML-like diagram verification, scroll-driven story verification, export verification, or guidance on avoiding brittle over-testing.
---

# Testing Data Visualizations

## Overview

Use this skill when the main question is how to verify a visualization, not just how to render one. Testing charts means protecting analytical truth, interaction behavior, rendering stability, and product integration without turning every pixel into a brittle contract.

Default assumption: use the smallest test mix that catches wrong numbers, broken interactions, and obvious visual regressions. Favor deterministic fixtures and targeted image baselines over giant snapshot suites.

## Choose This Skill When

- the user asks how to test a chart, dashboard, or visualization component
- screenshot testing, image diffing, or visual regression is the main concern
- the user needs help deciding what to mock and where to mock it
- the question is about unit versus component versus E2E coverage
- a live dashboard, export flow, or embedded chart needs QA strategy
- the user wants help trimming a brittle or overgrown chart test suite

## Working Pattern

1. Identify the highest-risk failures:
   - wrong transforms, aggregation, binning, stacking, or sorting
   - wrong scale domain, legend mapping, or annotation placement
   - broken hover, focus, selection, brush, or cross-filter behavior
   - mobile layouts that put controls or prose before the main visualization, hide the chart behind settings, or fail to return to the chart after Apply, Cancel, Reset, or close
   - touch interactions with tiny hit targets, hover-only values, missing drag alternatives, scroll hijacking, or broken pinch/zoom ownership
   - on-screen keyboard and visual viewport regressions that cover the main evidence or the only critical action
   - operational workspace regressions where outline trees, filters, selected marks, central viewport, URL state, and inspectors fall out of sync
   - mobile capability regressions where AR, camera, motion, vibration, notification, or geolocation prompts appear too early, lack fallbacks, or become required without user approval
   - spotty-connection regressions where live visualizations blank out, lose stale indicators, mislabel partial data, or fail to reconnect gracefully
   - wheel-zoom, pinch, or drag interactions that also scroll the page or leak scroll chaining to the document
   - clipping, overlap, layout drift, or export mismatch
   - project changes or implementation code that began before the user approved a required generated design concept
   - Codex image-generated concepts whose implementation preserves only the vibe or pixels but loses the claim, source context, caveat, evidence hierarchy, layout contract, or interaction staging
   - generated asset crop, overlay alignment, or label-safe region regressions
   - Canvas or WebGL render readiness, context loss, blank frames, high-DPI scaling, and overlay alignment
   - WebGL fallback duplication where a fallback remains visible behind or above the primary scene
   - globe, map, terrain, or cutaway coordinate-frame regressions where markers, labels, textures, hit testing, and camera focus no longer align
   - interaction state-machine regressions where hover, selection, expansion, pause/resume, drag, wheel, reset, close, or idle behavior changes meaning
   - animated story states whose first frame, key frames, or final frame no longer communicate the claim
   - scrollytelling or parallax states that desynchronize text, data layers, media, trigger ranges, or reduced-motion fallbacks
   - composite reports, decks, or stories where embedded visual layers bypassed specialist mini-briefs and became generic chart cards
   - UML-like or software architecture diagrams with stale generated source, invalid relationships, broken import/export, layout overlap, lost source IDs, or round-trip drift
   - fictional or synthetic story simulations whose seeded data no longer supports the editorial claim, route ranking, event timing, or derived comparisons
   - stale, empty, partial, loading, or failure state regressions
2. Choose the lightest effective layer:
   - unit tests for pure data shaping and formatting logic
   - component tests for public chart contracts and interaction callbacks
   - visual regression for layout-sensitive and appearance-sensitive states
   - E2E tests for real user workflows, async data behavior, and export paths
3. Make rendering deterministic before asserting:
   - fixed viewport and container size
   - stable fonts, theme tokens, locale, and timezone
   - reduced or disabled animation
   - reduced-motion and final-state fixtures for animated stories
   - deterministic scroll position, viewport size, scene id, progress value, and media readiness for scrollytelling stories
   - deterministic WebGL camera, clock, particle seed, device pixel ratio, and quality settings
   - seeded or fixture-backed data
   - fixed generated asset fixtures or checked-in placeholders instead of live generation inside tests
   - approved large-screen and mobile concept screenshots or references plus a semantic design contract fixture, locked/flexible element fixture, concise concept-review bullet summary, and user approval record for concepted visualization work
   - deterministic desktop, mobile portrait, and optional mobile landscape viewport sizes
   - deterministic operational workspace fixtures for mode, selected entity, filters, outline scroll, inspector state, zoom or camera, and mobile panel state
   - visual viewport or keyboard-open fixture for input-heavy mobile views
   - mocked online, offline, delayed, stale, partial, and reconnect states for live/mobile data
   - mocked permission-denied and unsupported states for AR, camera, motion, vibration, notification, and geolocation paths when used
   - fixed fictional simulation seeds plus invariant checks for entity counts, event windows, value ranges, ranking outcomes, and summary consistency
   - explicit render-ready signals before capture
4. Mock at the boundary:
   - prefer mocked network responses, data loaders, or repository adapters
   - keep transform and render logic real whenever practical
   - maintain canonical, edge-case, and stress fixtures
5. Define the non-goals:
   - do not test third-party chart library internals
   - do not duplicate the same assertion at every layer
   - do not baseline volatile states unless the volatility is the feature
6. When the visualization is operational or live, include stale, delayed, empty, and degraded modes.

## Coverage Heuristics

- Unit tests are appropriate for scales, domains, bin boundaries, sort rules, label formatting, tooltip payload shaping, color assignment, selection reducers, and any logic that can fail without rendering.
- Component tests are appropriate for legends, axis labels that matter semantically, accessible names, empty and error states, callback payloads, interaction wiring, and conditional UI around the chart.
- Screenshot or image tests are appropriate for overlap, clipping, tick collisions, annotation placement, color regressions, dense mark readability, and regression-prone layout states.
- For art-directed editorial stories, screenshot tests are appropriate for first frame, selected key frames, final frame, generated-asset alignment, mobile crop behavior, and mobile portrait or landscape contract fidelity.
- For concept-first visualization work, pair visual regression with semantic fidelity checks against the shared design workflow: approved concept references, recorded review bullets, implementation-after-approval evidence, locked and flexible elements, approved deviations, title claim, required comparison, denominator, scale, caveat, source visibility, measured/estimated/schematic styling, and data-bound label preservation.
- For scrollytelling and parallax stories, cover enter, exit, reverse scroll, fast scroll, resize, reduced-motion, stacked mobile fallback, and static key frames.
- For fictional visual stories, add data invariant tests before visual regression: deterministic seed output, minimum richness layers, expected event timing, primary claim truth, and derived summary agreement.
- E2E tests are appropriate for cross-chart coordination, URL or filter state, live refresh behavior, drill-down, exports, downloads, and embedding or routing flows.
- For Canvas or WebGL charts, rely more on data-contract tests, interaction tests, render-ready markers, canvas-pixel sanity checks, context-loss coverage, and targeted visual baselines than on DOM snapshots.
- For advanced WebGL/geospatial/cutaway work, include desktop, mobile portrait, and optional mobile landscape screenshots, a no-WebGL fallback screenshot, a nonblank canvas-pixel or first-frame check, coordinate alignment spot checks, and live interaction smoke tests for drag, wheel, click, tap, hover, keyboard, reset, expand, close, and pinch as applicable.
- For mobile dashboards and live views, cover last-known-good rendering, stale/live/offline/partial badges, delayed events, reconnect, background/resume, lower-frequency degradation, notification opt-in, and vibration or alert fallbacks when used.
- For particle or flow animation, capture first frame, a representative key frame, final or paused state, and reduced-motion fallback rather than baselining every frame.
- For UML-like diagrams, test parser/model normalization, semantic diagnostics, layout fixtures, interaction states, export snapshots, and source round-tripping when the product promises it.

## Output Expectations

- Propose a layered test plan instead of a single-tool answer.
- Separate data correctness, visual stability, and workflow coverage.
- Explain where real data, mocked data, and synthetic fixtures each belong.
- Call out brittleness risks and how to keep the suite deterministic.
- When implementing tests, start with the narrowest high-value slice before scaling coverage.
- For visual stories, include a human review checklist in release notes when imagery, WebGL, particles, 3D, or animation materially affects interpretation.
- For concepted work, include the shared workflow evidence: approval status, approved concept references, concise review bullets, visual design contract, locked/flexible element record, mobile/landscape continuation record, material mismatches, fixes or approved deviations, and semantic fidelity QA results.
- For mobile-capable browser work, include screenshot or interaction checks for mobile portrait, mobile landscape when justified, main-visualization visibility, settings return path, touch targets, hover replacement, drag alternatives, keyboard-open viewport, spotty connection, and permission-denied fallbacks.
- For operational workspaces, include checks for command bars, outline/filter/detail panels, default selection, synchronized inspector state, pan/zoom/reset, empty-surface click versus drag, URL restore, and mobile command-panel behavior.
- For composite deliverables, include embedded visualization self-use review notes: each layer's specialist owner, mini-brief, QA check, and delegated or local fresh-pass status.
- For simulated stories, include data-richness and self-use-gate review notes: which specialist skill shaped each embedded visualization, which mini-brief it followed, and which invariants prove the fictional data still supports the story.

## References

- Shared theory:
  - `../../references/foundations/implementation-design-and-tradeoffs.md`
  - `../../references/foundations/meaning-preserving-visual-design-workflow.md`
  - `../../references/foundations/embedded-visualization-self-use.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
  - `../../references/foundations/operational-visualization-workspaces.md`
- Skill references:
  - `./references/test-level-selection.md`
  - `./references/unit-and-component-tests.md`
  - `./references/visual-regression-and-image-testing.md`
  - `./references/data-mocking-and-fixtures.md`
  - `./references/e2e-dashboard-and-export-strategies.md`
  - `./references/avoiding-brittle-over-testing.md`
- Useful templates:
  - `../../assets/templates/visualization-test-plan.md`
  - `../../assets/templates/visual-design-contract.md`
  - `../../assets/templates/advanced-interactive-visualization-contract.md`
  - `../../assets/templates/interactive-uml-test-plan.md`
  - `../../assets/templates/playwright-visual-regression-starter.ts`
- Adjacent skills:
  - `../scrollytelling-and-parallax-data-visualization/SKILL.md`
  - `../uml-and-software-architecture-visualization/SKILL.md`
  - `../react-and-nextjs-data-visualization/SKILL.md`
  - `../typescript-data-visualization-engineering/SKILL.md`
  - `../../references/foundations/fictional-data-story-simulation.md`
  - `../dashboards-and-real-time-visualization/SKILL.md`
  - `../accessibility-and-inclusive-visualization/SKILL.md`

## Representative Prompts

- "How should I test this React chart component?"
- "Set up screenshot testing for this dashboard without making it flaky."
- "What data should I mock for this D3 or Canvas visualization?"
- "Which parts of this chart deserve unit tests versus E2E tests?"
- "Help me design visual regression coverage for a live monitoring screen."
- "Review this visualization test suite and tell me what to delete."
- "Design tests for a parallax scrollytelling story without making screenshots flaky."
- "Design tests for an interactive UML, ERD, state machine, flow, dependency, or architecture diagram."

Referenced files: 7

View saved version →

---
name: threejs-data-visualization
description: Render WebGL-accelerated data visualizations with Three.js, raw WebGL, deck.gl, luma.gl, PixiJS, Sigma.js, Plotly WebGL traces, ECharts GL, CesiumJS, Babylon.js, or related GPU libraries. Use when the visualization needs true spatial structure, dense 2D or 3D GPU rendering, particle or flow animation, volumetric views, or interactive exploration that adds real analytical value.
---

# Three.js and WebGL Data Visualization

## Overview

Use this skill when the user truly benefits from 3D, GPU-heavy 2D, shader-driven animation, or WebGL-accelerated interaction. Three.js is appropriate for volumetric data, 3D point clouds, spatial trajectories, surfaces, scientific or immersive scenes, and custom particle systems. WebGL or WebGL-backed libraries are also appropriate for dense 2D scatterplots, animated networks, flow maps, particle trails, GPU aggregation, or custom shader effects that exceed practical SVG/DOM limits and are not a good fit for Canvas2D.

Default assumption: use the simplest truthful renderer that meets the scale and interaction requirements. 3D is justified only when depth carries analytical meaning. WebGL is justified when GPU throughput, shader control, large mark counts, or animation quality matter enough to offset accessibility, export, debugging, bundle, and GPU-memory costs. Cosmetic 3D or decorative particles are regressions.

Mobile GPUs, touch gestures, battery, thermal limits, and permissions can change the renderer choice. Use `../../references/foundations/mobile-first-responsive-visualization.md` for mobile portrait/landscape contracts, AR/camera/motion/vibration decisions, visual viewport behavior, spotty connection handling, and touch-first controls.

## Choose WebGL When

- the data is inherently spatial, volumetric, trajectory-based, or surface-based
- depth, orbit, slicing, or perspective reveals structure unavailable in 2D
- an editorial story needs camera states to reveal a meaningful surface, volume, terrain, or multiaxis relationship
- GPU instancing, texture-backed data, or shader-based rendering materially improves scale
- dense 2D plots, networks, or maps need hundreds of thousands to millions of marks, continuous pan or zoom, or real-time filtering
- animated flow, trips, particles, or transitions must remain smooth without generating thousands of DOM or SVG elements
- the view needs GPU picking, custom blending, post-processing, or shader effects tied to data attributes
- the experience needs immersive or exploratory navigation
- AR or camera-backed spatial inspection adds analytical value and has a non-permission fallback

## Avoid WebGL When

- the same comparison is clearer in 2D
- labels and exact values dominate the task
- the chart will mostly be consumed as a static document
- a declarative grammar, D3/SVG, or Canvas2D can handle the mark count with less maintenance and better export/accessibility
- the required effect is mostly decoration, novelty, or attention capture without a specific analytical verb
- the page will show many small charts where WebGL context pressure and GPU memory would outweigh per-chart speed

## Library Selection

- Three.js: custom 3D scenes, point clouds, instancing, particles, shader materials, camera-led stories, and 3D analytical surfaces.
- deck.gl: high-volume geospatial and non-geospatial layers, GPU aggregation, picking, animated trips, arcs, paths, point clouds, and overlays on MapLibre, Mapbox, Google Maps, or ArcGIS.
- luma.gl: low-level WebGL2 or WebGPU-leaning GPU programming when deck.gl abstractions are too high-level but raw WebGL would be too much boilerplate.
- raw WebGL2: maximum control for custom shaders, data textures, transform feedback, framebuffers, or unusual render pipelines; reserve for teams comfortable owning GPU lifecycle and debugging.
- regl or TWGL: lighter low-level WebGL wrappers when custom shaders are needed without a full scene engine; regl is especially good for command-style, state-minimized rendering.
- PixiJS: GPU-accelerated 2D sprites, particles, texture atlases, labels-as-sprites, playful dashboards, and 2D editorial animation where a scene graph helps.
- Sigma.js: large interactive node-link graphs where WebGL rendering, graph layouts, hover states, and graph-specific affordances matter more than custom shader freedom.
- Plotly WebGL traces: fast scientific or product charts when a high-level declarative API is more important than custom rendering control.
- ECharts GL: configuration-driven 3D charts, globe views, and WebGL acceleration inside an ECharts product stack.
- MapLibre GL JS or Mapbox GL JS: vector-tile product maps, data-driven style layers, camera motion, heatmaps, and custom layers.
- CesiumJS: 3D globe, terrain, 3D Tiles, time-dynamic geospatial visualization, and high-precision WGS84 scenes.
- Babylon.js: full 3D engine features such as GPU particles, physics, rich materials, large-world rendering, and WebXR when the work is closer to an interactive simulation than a chart.

## Particle and Flow Effects

Use particle effects only when they make movement, accumulation, attention, or state more legible:

- flow particles along network edges, routes, pipes, links, or migration paths when direction and rate are the story
- trip trails or fading path segments when temporal progression matters
- pulsing, halo, shimmer, ember, or sparkle effects for selected, anomalous, high-risk, newly changed, or user-focused marks
- density particles, dot advection, or flow fields when a field is continuous and exact individual paths are not meaningful
- restrained fire, heat, glow, or hazard particles only when the metaphor matches the domain and does not trivialize serious subject matter

Do not use particles when they obscure totals, imply individual entities that are not in the data, overstate certainty, glamorize harm, or compete with labels and comparison tasks. Always provide a reduced-motion fallback and a static final or key frame.

## Default Architecture

1. Choose the renderer from data shape and interaction load before choosing visual style.
2. Prefer orthographic projection for chart-like 3D or 2.5D scenes.
3. Use perspective only when depth cues matter.
4. Keep data-to-scene transforms explicit and reversible.
5. Use GPU-friendly primitives:
   - `BufferGeometry`
   - instancing
   - points
   - sprites or billboards
   - texture atlases
   - typed arrays and binary attributes
   - shader materials when needed
6. Batch static marks, keep dynamic attributes narrow, and avoid re-uploading full buffers every frame.
7. Assess how many scenes may be visible at once, because GPU memory, context pressure, and overlay complexity change the recommendation.
8. Keep labels, legends, controls, and rich annotation in DOM or SVG overlays unless the scene truly demands in-canvas text.
9. For editorial stories, define named camera or animation states as part of the annotation plan: overview, focus, comparison, reveal, final.
10. Keep generated textures, basemaps, or illustrated backdrops separate from data geometry so they can be reviewed and swapped.
11. For custom shaders, define the data contract first: attributes, uniforms, textures, derived values, picking IDs, and fallbacks.
12. For particles, define emission source, path or field, speed, lifetime, color, opacity curve, decay, selection behavior, and reduced-motion state before coding.
13. For advanced scenes, complete `../../assets/templates/advanced-interactive-visualization-contract.md` before implementation. Name one primary scene owner, a true fallback path, coordinate frames, camera states, picking model, animation clock, interaction state machine, render-ready signal, and screenshot QA.
14. Never let a fallback or helper renderer duplicate the primary visual while WebGL is active. One renderer owns the focal scene; fallbacks appear only when the primary scene fails or is intentionally disabled.
15. For mobile, cap DPR or quality when needed, pause offscreen/inactive loops, lazy-load heavy assets with reserved dimensions, and define stale/offline rendering for streamed or tiled data.

## Interaction Rules

- Support reset view, focus target, and orientation cues.
- Keep camera behavior predictable.
- Use shortest-path rotation or named camera states when focusing spherical or cyclic data.
- Use brushing, filtering, aggregation, level of detail, or slicing when full-scene density becomes unreadable.
- Pair 3D navigation with 2D summaries where possible.
- Prefer GPU picking, spatial indexes, ID buffers, or screen-space nearest-mark picking for dense hit testing; avoid per-mark DOM overlays except for selected or focused marks.
- Respect reduced-motion by providing direct camera-state controls, paused particles, a stepped sequence, or a static key-frame sequence.
- Preserve browser interaction expectations. If the scene captures wheel, pinch, or drag, provide clear reset and alternate controls.
- On mobile, provide tap/focus selection, step-through or search for dense marks, explicit zoom buttons or two-finger gestures, and a portrait fallback when landscape is the richer inspection mode.
- Use WebXR, camera, device motion, vibration, notifications, or geolocation only when the capability has a named analytical purpose, a user-initiated permission moment, and an accessible fallback.

## Output Expectations

- Justify the WebGL choice against SVG, DOM, Canvas2D, and declarative options.
- Preserve orientation and scale cues.
- Provide screenshot or image export paths when the result must appear in reports.
- Keep labels, legends, and summaries readable in 2D overlays when exact reading matters.
- For animated WebGL, state the animation verb, frame budget, clock model, reduced-motion behavior, and static fallback.
- For particle effects, state what each particle represents, what it must not be interpreted as, and how opacity/lifetime/rate map to data.
- For glows, pulses, halos, thickness, blur, shimmer, or selection effects, state the exact data field or interaction state they encode. If the effect has no mapping, remove it.
- For editorial 3D or particle stories, state the first frame, final frame, camera or motion states, and 2D/static fallback.
- For new work, include a technical design section covering simultaneous scene count, GPU memory, context pressure, buffer update patterns, interaction costs, and maintenance tradeoffs versus Canvas2D and SVG/DOM alternatives.
- For mobile work, include portrait and optional landscape framing, touch/pinch/camera-control behavior, DPR/quality budget, battery/thermal assumptions, permission-gated capability fallbacks, and spotty-connection behavior.
- For globe, terrain, or map-like scenes, include coordinate-alignment checks for texture, basemap, markers, labels, hit testing, camera focus, and fallback geometry.

## References

- Shared theory:
  - `../../references/foundations/task-abstraction-and-chart-selection.md`
  - `../../references/foundations/art-directed-interactive-visual-stories.md`
  - `../../references/foundations/perception-color-and-encoding.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
  - `../../references/foundations/implementation-design-and-tradeoffs.md`
- Skill references:
  - `./references/when-3d-is-justified.md`
  - `./references/scene-architecture-and-encodings.md`
  - `./references/gpu-scaling-and-interaction.md`
  - `./references/webgl-library-selection.md`
  - `./references/webgl-2d-animation-patterns.md`
  - `./references/particle-effects-and-flow.md`
  - `./references/scene-readiness-and-interaction-qa.md`
  - `./references/cutaway-terrain-and-domain-scenes.md`
- Templates:
  - `../../assets/templates/advanced-interactive-visualization-contract.md`

## Representative Prompts

- "Visualize trajectories in 3D with brushing and focus."
- "Render a dense point cloud with GPU instancing."
- "Build a volumetric or surface view with supporting 2D annotations."
- "Tell me whether this should stay 2D or move to Three.js."
- "Design a Three.js scene that still reads clearly in screenshots."
- "Build a WebGL scatterplot or network that can animate hundreds of thousands of marks."
- "Use particles to show flow between nodes without making the chart feel decorative."
- "Choose between deck.gl, Three.js, PixiJS, regl, raw WebGL, and Canvas2D for this visualization."

Referenced files: 9

View saved version →

---
name: typescript-data-visualization-engineering
description: Build typed data visualizations in TypeScript. Use when the user wants TypeScript visualization code, typed data models, browser visualization components, UML-like diagram models, interactive graph or architecture diagram contracts, scroll-driven scene contracts, library selection guidance, or a maintainable visualization architecture beyond React- or Next-specific concerns.
---

# TypeScript Data Visualization Engineering

## Overview

Use this skill when the visualization must live in a TypeScript application. The focus is not just chart rendering. The focus is reliable data contracts, clear component boundaries, maintainable integration architecture, and a renderer that fits the product surface.

If the request is specifically about React components, client or server boundaries, hydration, dynamic loading, or Next.js delivery constraints, route first to `../react-and-nextjs-data-visualization/SKILL.md`.

If the request is primarily about test strategy, mocks, screenshot coverage, or deciding which chart logic deserves unit tests, route first to `../testing-data-visualizations/SKILL.md`.

## Renderer and Library Selection

- D3: custom chart math, behaviors, and bespoke SVG or hybrid views.
- Observable Plot or Vega-Lite wrappers: fast, declarative 2D charts.
- Visx, Recharts, ECharts, or Chart.js: product-oriented chart layers when their abstraction fits.
- Canvas2D adapters: dense flat views, immediate-mode rendering, and custom hit testing where Canvas is simpler than WebGL.
- WebGL adapters: dense GPU-scale 2D, particles, flow animation, custom shaders, GPU picking, or true 3D.
- Three.js: spatial, volumetric, instanced, particle, or camera-led 3D scenes.
- deck.gl, PixiJS, Sigma.js, Plotly WebGL traces, ECharts GL, MapLibre, CesiumJS, luma.gl, regl, TWGL, or raw WebGL2 when their renderer model matches the data shape.
- Scrollama, CSS ScrollTimeline/ViewTimeline, Motion `useScroll`, or GSAP ScrollTrigger when a scroll-driven scene controller is needed.
- Image generation pipeline: produced assets, transparent cutouts, textures, and scene backgrounds that remain separate from data-bound overlays.
- Mermaid, PlantUML/Kroki, Graphviz/WASM, D2, Structurizr, React Flow, Cytoscape.js, Sprotty, JointJS, GoJS, ELK, or Dagre when the surface is UML, ERD, C4, flow, state, schema, dependency, architecture, or interactive diagramming.

## TypeScript Rules

1. Define the data schema before rendering.
2. Validate external data at the boundary.
3. Keep derived chart geometry in typed functions.
4. Separate:
   - data loading
   - transformation
   - scale creation
   - rendering
   - interaction state
5. Model selections, filters, tooltip payloads, URL state, persisted preferences, and saved-view payloads as explicit types.
6. Define a canonical view-state codec for shareable state: parse, validate, normalize defaults, serialize in stable order, and migrate or reject stale schema versions.
7. Keep ephemeral interaction state separate from durable state. Hover, drag-in-progress, animation frame, and pointer position should not leak into saved URLs or persisted workspaces.
8. For new work, assess the intended number of simultaneous visualization instances so the architecture reflects page-level costs instead of single-instance demos.
9. For editorial systems, model reusable design tokens, annotation specs, label placement rules, artifact modes, motion states, asset manifests, color-role ledgers, and rubric checks as typed data instead of ad hoc strings inside render code.
10. For fictional, synthetic, or illustrative stories, model the data-generating world explicitly. Include seed, assumptions, entities, temporal records, spatial or physical substrate, event windows, outcomes, derived comparisons, and invariants. Use `../../references/foundations/fictional-data-story-simulation.md`.
11. For concepted editorial, report, deck, generated-image, animation, scrollytelling, or existing-page integration work, use `../../references/foundations/meaning-preserving-visual-design-workflow.md` and `../../references/foundations/mobile-first-responsive-visualization.md`. Apply the shared workflow for concept images, large-screen/mobile variants, approval or iteration, and typed semantic design contracts for evidence locks, responsive states, generated assets, fallbacks, and approved deviations.
12. For scrollytelling or parallax, use `../scrollytelling-and-parallax-data-visualization/SKILL.md` and define a typed scene contract:
   - visible data layers
   - generated or illustrated assets
   - media assets
   - camera or transform state
   - annotation state
   - trigger or progress range
   - interaction state
   - static key frame
   - reduced-motion fallback
13. For generated imagery, keep asset metadata explicit: prompt version, source, dimensions, focal crop, label-safe regions, alt text, continuity group, and data fields that bind to it.
14. For UML-like or software architecture diagrams, use `../uml-and-software-architecture-visualization/SKILL.md` first and keep a renderer-neutral diagram model separate from Mermaid, PlantUML, React Flow, Cytoscape.js, Sprotty, JointJS, GoJS, DOT, D2, or Structurizr adapters.

## React Guidance

- Prefer React-owned structure and D3-owned math when both are in play.
- Keep expensive transforms out of repeated render paths.
- Use clear component boundaries between chart container, render layer, and controls.
- Plan export paths if the chart must appear in reports or documents.
- Treat specs, scales, derived marks, and tooltip payloads as explicit typed interfaces.
- Treat URL codecs, saved-view payloads, storage keys, schema versions, and invalid-state fallbacks as part of the visualization API.
- Treat editorial elements as first-class props: insight title, subtitle, artifact mode, source, notes, annotations, direct labels, motion states, image assets, large-screen layout, mobile portrait layout, optional mobile landscape layout, and mobile fallback.
- Model mobile interaction and resilience explicitly: pointer mode, touch target/hit-area policy, hover replacement, pinch/drag ownership, visual viewport or keyboard state, stale/offline/partial data state, permission-gated capability availability, and reduced-motion/low-power mode.
- For embedded visual stories, make specialist skill ownership explicit in data contracts or implementation notes so maps, swarms, distributions, flow layers, and export fallbacks are not treated as generic components.

## Output Expectations

- Pick libraries that fit the app architecture, not generic popularity.
- Keep types useful at runtime boundaries.
- Call out whether the chart is DOM, Canvas, WebGL, or hybrid.
- For WebGL, call out whether the implementation is Three.js, deck.gl, PixiJS, Sigma.js, Plotly/ECharts GL, MapLibre/Cesium, luma.gl/regl/TWGL, raw WebGL, or a hybrid overlay.
- For particles or flow animation, state what each particle represents, the clock model, reduced-motion behavior, and static fallback.
- For art-directed stories, call out whether imagery is generated or hand-authored, which layers remain data-bound, and how still-frame and reduced-motion fallbacks are represented.
- For concepted stories or figures, use the shared design workflow for concept images, approval status, binding semantic design contract type, approved references, locked and flexible elements, data-bound layer contracts, generated asset metadata, mobile/landscape continuation, approved deviations, and semantic fidelity checks.
- For scroll-driven stories, call out the scene contract, controller, native-scroll behavior, static frames, reduced-motion path, and mobile fallback.
- For interactive tools, call out the URL view-state contract, persisted-state tiers, precedence rules, copy-link behavior, back/forward behavior, and collapsed-control state.
- For mobile-capable tools, call out the mobile portrait and optional landscape contracts, main-visualization visibility rule, touch/pinch/keyboard behavior, spotty-connection handling, and justified AR/camera/motion/vibration/notification capabilities.
- For fictional stories, call out the simulation seed, regeneration path, data richness layers, invariants, and derived datasets that support each embedded visualization.
- Include a technical design section for new work covering instance-count assumptions, performance implications, and maintenance tradeoffs of the chosen contracts and renderer.

## References

- Shared theory:
  - `../../references/foundations/editorial-infographic-system.md`
  - `../../references/foundations/art-directed-interactive-visual-stories.md`
  - `../../references/foundations/meaning-preserving-visual-design-workflow.md`
  - `../../references/foundations/fictional-data-story-simulation.md`
  - `../../references/foundations/task-abstraction-and-chart-selection.md`
  - `../../references/foundations/perception-color-and-encoding.md`
  - `../../references/foundations/shareable-state-and-persistence.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
  - `../../references/foundations/implementation-design-and-tradeoffs.md`
- Skill references:
  - `../react-and-nextjs-data-visualization/SKILL.md`
  - `../uml-and-software-architecture-visualization/SKILL.md`
  - `../scrollytelling-and-parallax-data-visualization/SKILL.md`
  - `../testing-data-visualizations/SKILL.md`
  - `./references/library-selection-for-builders.md`
  - `./references/react-and-framework-boundaries.md`
  - `./references/types-and-data-contracts.md`
  - `./references/export-and-product-integration.md`

## Representative Prompts

- "Build a typed React charting system."
- "Design the TypeScript chart contracts behind a React or Next.js visualization surface."
- "Design the typed scene contract for a scrollytelling or parallax data story."
- "Choose a TypeScript visualization library for this product."
- "Convert this D3 prototype into maintainable TypeScript."
- "Embed Vega-Lite or Observable Plot in a React app without losing control."
- "Design the types for selections, tooltips, and chart data contracts."
- "Design typed contracts for an interactive UML, ERD, architecture, state machine, or dependency diagram."

Referenced files: 5

View saved version →

---
name: uml-and-software-architecture-visualization
description: Design, critique, read, write, render, and implement UML and UML-like software diagrams. Use when the user mentions UML, sequence diagrams, class diagrams, activity diagrams, state machines, use case diagrams, component diagrams, deployment diagrams, object diagrams, package diagrams, profile diagrams, timing diagrams, communication diagrams, interaction overview diagrams, composite structure diagrams, ERDs, database schema diagrams, C4, BPMN, swimlanes, flowcharts, network diagrams, application architecture diagrams, software architecture diagrams, diagram-as-code, model-as-code, XMI, UMLDI, PlantUML, Mermaid, Graphviz DOT, D2, Structurizr, DBML, diagrams.net/draw.io, Kroki, or interactive diagram editors and explorers.
---

# UML and Software Architecture Visualization

## Overview

Use this skill when the visualization is about system structure, behavior, process, state, data models, dependencies, architecture, or interactions rather than numeric charting alone. The job is to choose the clearest notation, source format, renderer, and interaction model for the audience.

Default assumption: use formal UML when notation precision, methodology alignment, or model interchange matters. Use a UML-like diagram such as C4, ERD, BPMN, flowchart, swimlane, dependency graph, or architecture map when that communicates the user's actual question with less ceremony.

When the main challenge is automatic placement, crossing reduction, routing style, overlap removal, or layout stability rather than notation selection, route through `../node-link-and-diagram-layout/SKILL.md` before locking in a renderer.

For browser or app diagrams, use `../../references/foundations/mobile-first-responsive-visualization.md` so mobile portrait, optional landscape, touch, keyboard, search, and main-diagram visibility are planned before implementation.

For architecture consoles, schema explorers, state-machine inspectors, dependency maps, or other dense repeated-use diagram products, also use `../../references/foundations/operational-visualization-workspaces.md` so the shell, outline, inspector, command bar, mobile panels, URL state, and pan/zoom behavior are designed as part of the diagram.

## Core Workflow

1. Identify the modeling job:
   - static structure, runtime interaction, workflow, lifecycle state, deployment topology, dependency graph, database schema, architecture context, or implementation detail
2. Identify the audience:
   - business stakeholder, analyst, product owner, architect, developer, operator, auditor, or onboarding reader
3. Choose formal UML or a UML-like alternative:
   - formal UML for standard semantics, XMI, UMLDI, or tooling interchange
   - C4 for layered software architecture communication
   - ERD or DBML for relational schemas and data model documentation
   - BPMN or swimlane activity diagrams for business processes and handoffs
   - flowcharts or state machines for control flow and lifecycle logic
   - network or dependency diagrams for topology, coupling, and impact analysis
4. Select the diagram family and scope:
   - one primary question per diagram
   - one abstraction level per view unless the user explicitly needs a bridge diagram
   - source IDs, names, stereotypes, technologies, and relationship labels preserved when available
5. Choose the source or interchange format:
   - XMI/UMLDI for formal model exchange
   - PlantUML, Mermaid, DOT, D2, Structurizr DSL, DBML, or BPMN XML for source-backed documentation and CI
   - JSON graph models when building a product renderer or interactive editor
6. Choose the layout strategy when automatic arrangement matters:
   - route to `../node-link-and-diagram-layout/SKILL.md` for layered, tree, force, radial, planarization, routing, overlap, and stability decisions
   - preserve source order, port order, and grouping constraints when they are semantically meaningful
7. Choose the renderer or editor stack:
   - static image generation, documentation embed, notebook/script, web component, interactive explorer, or editable diagramming product
8. Define the normalized model contract before rendering:
   - nodes, edges, compartments, ports, lanes, groups, hierarchy, labels, metadata, source IDs, layout hints, and validation diagnostics
9. Plan export, accessibility, and tests:
   - SVG/PNG/PDF/HTML outputs, text alternatives, keyboard paths, deterministic layout fixtures, semantic validation, and visual regression where layout matters
10. For multi-view architecture explorers, choose a calm default reading state:
   - show one dense subdiagram at a time, especially for schemas and state machines
   - keep side panels as compact controls and outlines, not nested cards
   - render all relationships quietly by default, then emphasize hover and selection paths
   - use a synced navigation tree so users can jump among topology entities, tables, states, and transitions without hunting inside the canvas
   - prefer scrollable intrinsic canvases over shrinking node text below readable size
   - on mobile, show a focused default subdiagram or outline plus detail path instead of stacking every control above the diagram
   - use mobile landscape for wide schema, sequence, or dependency inspection when it improves legibility, while preserving a useful portrait entry point
   - use compact command bars, synchronized outlines, central scrollable canvases, and inspector rails instead of equal-weight cards

## Diagram Selection Defaults

- Sequence diagram: message order across actors, services, or objects.
- Communication diagram: collaboration topology when the object network matters as much as ordering.
- Activity diagram or swimlane: workflow, branching, parallel work, ownership, and handoffs.
- State machine: lifecycle rules, event-driven behavior, allowed transitions, and invalid states.
- Class or object diagram: code-level structure, interfaces, relationships, snapshots, and domain object shape.
- Component, package, deployment, or C4 diagram: architecture structure at the right abstraction level.
- Use case diagram: actor goals and system boundary, usually early requirements or stakeholder alignment.
- ERD, DBML, or database schema diagram: tables, relationships, keys, constraints, and schema ownership.
- BPMN: business process execution semantics, events, gateways, pools, tasks, and process interchange.
- Flowchart: lightweight control flow when UML activity or BPMN would be too formal.
- Network or dependency diagram: topology, coupling, blast radius, graph traversal, and modularity.

## Stack Defaults

- Documentation-first static diagrams: prefer PlantUML or Mermaid, with SVG export when labels must stay crisp.
- Formal UML exchange: use XMI plus UMLDI where diagram geometry must travel with model semantics; expect vendor-specific gaps.
- Architecture model-as-code: prefer Structurizr DSL for C4; use C4-PlantUML or Mermaid C4 when docs integration is more important than a reusable model.
- Database schema diagrams: prefer DBML, SQL-derived ERD tooling, Mermaid ER, or PlantUML IE/ER.
- Diagram source rendering: use Mermaid, PlantUML, D2, Graphviz DOT, Structurizr DSL, DBML, BPMN XML, or Kroki when text DSL rendering is needed.
- TypeScript or web rendering: use Mermaid for simple docs, React Flow for editable node-edge UIs, Cytoscape.js for graph analysis and larger networks, Sprotty for model-driven diagram tools, JointJS or GoJS for full-featured diagram editors, and ELK or Dagre for auto-layout.
- Bespoke SVG/D3: use only when the diagram needs custom annotation, visual polish, or product-specific composition that diagram DSLs cannot express cleanly.
- For dense topology, ERD, or state-machine explorers, route layout choice through `../node-link-and-diagram-layout/SKILL.md`, then prefer ELK or Dagre when adding a dependency is acceptable; if staying bespoke, implement an explicit layered layout, stable ranks, non-overlap spacing, routed edges, and focus-state filtering instead of relying on hand-placed nodes.

## Reference Guide

- Read `references/uml-diagram-types-and-selection.md` for formal UML diagram types, alternatives, and selection heuristics.
- Read `../node-link-and-diagram-layout/SKILL.md` when the main issue is node placement, crossing reduction, routing style, or overlap management.
- Read `references/formats-and-interchange.md` before reading, writing, converting, or round-tripping diagram formats.
- Read `references/typescript-web-rendering.md` for browser, TypeScript, React, and interactive renderer choices.
- Read `references/interactive-diagram-patterns.md` before designing interactive explorers or diagram editors.
- Read `references/quality-accessibility-export-testing.md` for semantic checks, accessibility, export, and QA.

## Output Expectations

- State the recommended diagram type and one fallback, with the reason tied to audience and modeling job.
- State whether the output is formal UML, UML-like, architecture model-as-code, graph visualization, or an editable diagram product.
- Identify the source format, renderer, export path, and any required conversion or validation.
- For generated diagrams, preserve source IDs and call out inferred relationships rather than presenting them as source truth.
- For interactive diagrams, define selection, pan/zoom, search, filtering, drill-down, editing, layout recalculation, keyboard access, export, and source round-tripping.
- For architecture views, keep abstraction levels consistent and label relationships with verbs or data/protocol semantics.
- For class and schema diagrams, control detail level so attributes, methods, constraints, and relationships do not overwhelm the primary question.
- For ERDs and database schemas, route foreign keys in dedicated gutters or ports; never let connectors run underneath table boxes or column text.
- Include a testing and accessibility plan when the diagram is part of a product surface or durable documentation workflow.
- For mobile diagrams, state portrait and optional landscape behavior, touch/pan/zoom ownership, search or step-through path, keyboard-open behavior, and how controls return users to the diagram.
- For explorer-style diagram products, state the workspace shell, navigation tree, default selection, inspector synchronization, URL state, pan/zoom/reset controls, and mobile command-panel behavior.

## Adjacent Skills

- Use `../visualization-strategy-and-critique/SKILL.md` when deciding whether a UML-like diagram is the right visual form.
- Use `../node-link-and-diagram-layout/SKILL.md` for graph-family classification, layout algorithms, routing, overlap removal, and stability.
- Use `../typescript-data-visualization-engineering/SKILL.md` for typed graph models, renderer contracts, and browser architecture.
- Use `../react-and-nextjs-data-visualization/SKILL.md` for React or Next.js integration.
- Use `../d3-data-visualization/SKILL.md` for bespoke SVG geometry, annotation, and polish.
- Use `../accessibility-and-inclusive-visualization/SKILL.md` for text alternatives, keyboard paths, contrast, and export accessibility.
- Use `../testing-data-visualizations/SKILL.md` for visual regression, interaction, and export test strategy.
- Use `../reports-pdfs-and-slide-automation/SKILL.md` for PDFs, decks, and document embedding.
- Use `../../references/foundations/mobile-first-responsive-visualization.md` for mobile diagram layout, touch, keyboard, and responsive QA.
- Use `../../references/foundations/operational-visualization-workspaces.md` for architecture consoles, schema explorers, state-machine inspectors, and repeated-use diagram workspaces.

## Representative Prompts

- "Choose the right UML or UML-like diagram for this system, process, or data model."
- "Read this XMI and summarize the class model."
- "Create a sequence diagram for OAuth login."
- "Make an interactive React dependency diagram."
- "Visualize my PostgreSQL schema."
- "Turn this PostgreSQL schema into an ERD or DBML diagram."
- "Which diagram should explain this checkout workflow?"
- "Compare Mermaid, PlantUML, Graphviz, D2, and Structurizr for this documentation site."
- "Make a state machine diagram and test invalid transitions."
- "Design a C4 model for this application architecture."

Referenced files: 6

View saved version →

---
name: visualization-strategy-and-critique
description: Choose, lay out, critique, and explain data visualizations. Use when the user asks what visualization fits a dataset or goal, how a chart, dashboard, operational workspace, UML-like diagram, or software architecture diagram should be composed or interacted with, asks for visual page design, a layout mockup, generated large-screen and mobile concept images, or to be shown what a visualization could look like, when domain-native contextual surfaces or graphical backgrounds may help, when scrollytelling or parallax might be appropriate, wants a critique of an existing visualization, or needs guidance grounded in trusted visualization theory and practice. For advanced visual design or page-layout prompts where composition affects understanding, Codex must generate and show both large-screen and mobile portrait image concepts before implementation or text-only design handoff, plus mobile landscape when needed.
---

# Visualization Strategy and Critique

## Overview

Use this skill when the hardest problem is not rendering marks. The hardest problem is deciding what evidence to show, what comparisons matter, what the audience must understand, how the surface should be composed, and which visual form makes that reasoning easiest.

Treat Tufte, Bertin, Cleveland and McGill, Tukey, Munzner, Few, Cairo, Ware, Shneiderman, Cole Nussbaumer Knaflic, Amanda Cox, Mike Bostock, and Jen Christiansen as working lenses. Use them to make decisions, not to decorate explanations.

Default assumption: the best interface is largely self-explanatory. If the user would need a paragraph or hover-only behavior to grasp the main comparison, simplify the layout, labeling, or default state before adding more prose.

Mobile and large screens are sibling strategy targets. Unless the user explicitly excludes one, choose a reading path and concept direction for both before treating responsive behavior as an implementation detail.

## Default Procedure

1. Define the question, decision, or claim the view must support.
2. Identify the audience and the stakes.
3. Classify the data and the required comparisons.
4. Write the insight title as a testable claim before sketching.
5. Choose the simplest visual form that makes the key comparison easiest to read.
6. For project schedules, roadmaps with task spans, milestones, dependencies, critical path, baselines, or resource plans, use `../gantt-chart-visualization/SKILL.md` before choosing a renderer. Treat MS Project, Primavera, Jira, GitHub Projects, Smartsheet, monday.com, Asana, ClickUp, Azure DevOps, CSV, TSV, XLSX, and JSON inputs as source-ingestion problems before chart-design problems.
7. For system structure, workflow, state, dependency, schema, code, or software architecture explanation, use `../uml-and-software-architecture-visualization/SKILL.md` before choosing formal UML, C4, ERD, BPMN, flowchart, swimlane, state machine, network, architecture map, or an interactive diagram renderer.
8. For editorial work, choose the artifact mode before the renderer: data-first chart, generated object marks, illustrated substrate, cartographic flow field, WebGL-accelerated 2D, particle or flow animation, 3D surface, or scrollytelling/parallax sequence.
9. Decide whether a meaningful domain surface should shape the view: field, court, track, floor plan, schematic, route, room, object, terrain, or other graphical context that helps explain position, roles, zones, mechanism, or flow.
10. For editorial infographics, report/deck figures, visual articles, composite layouts, animation, generated imagery, scrollytelling, parallax, or visualization placement inside an existing page, use `../../references/foundations/meaning-preserving-visual-design-workflow.md` and `../../references/foundations/mobile-first-responsive-visualization.md` when composition materially affects understanding. Apply those shared references for required concept generation, large-screen/mobile variants, approval or iteration, semantic design contracts, and implementation deferral.
11. For fictional, synthetic, or illustrative stories, use `../../references/foundations/fictional-data-story-simulation.md` before sketching. Require entity, temporal, spatial or physical, event, outcome, and derived comparison layers.
12. For reports, stories, parallax, editorials, visual articles, or decks with embedded visualizations, use `../../references/foundations/embedded-visualization-self-use.md` before composition. Inventory each visual layer, name the primary specialist owner, write a mini-brief for job, data shape, encoding, interaction, fallback, accessibility, QA, and fresh-pass status, and use authorized delegation or an explicit local specialist pass for substantial layers.
13. Keep labels and keys in the view or immediately beside it so decoding does not require hunting across the page.
14. If using visual references, extract the principle and state the original transformation for this dataset. Do not clone a publication layout, type style, palette, scene, or interaction cadence.
15. Decide what must be visible by default versus revealed interactively.
16. Compose a clear reading order: one focal view, subordinate context, and controls placed near the evidence they affect. On mobile, the main visualization must appear before or alongside settings, and settings must return the user to the affected view after Apply, Cancel, Reset, or close.
17. For operational consoles, architecture explorers, live dashboards, schema/state-machine inspectors, or repeated analytical workspaces, use `../../references/foundations/operational-visualization-workspaces.md` before sketching the shell. Decide the main viewport, outline/control rail, inspector, command/status bar, mobile panel model, default selection, and URL state together.
18. For new implementation work, turn the chart recommendation into a concise technical design that covers simultaneous instance count, renderer fit, performance, and maintenance tradeoffs.
19. For advanced WebGL, 3D, globe, geospatial, terrain, cutaway, particle, scrollytelling, or multi-layer interactive work, use `../../assets/templates/advanced-interactive-visualization-contract.md` after concept approval and before implementation. Require renderer ownership, coordinate-frame checks, mark semantics, interaction states, fallback/render-ready behavior, and QA.
20. Add annotation, narrative, imagery, motion, or small multiples only when they reduce interpretation cost.

## Editorial Infographic Mode

Use `../../references/foundations/editorial-infographic-system.md` when the user asks for an infographic, article visual, publication-quality chart, visual story, executive figure, or non-dashboard explanation.

- Start from the story sentence: what should the reader understand after 10 seconds?
- Replace topic titles with claim titles.
- Design custom composition around the evidence instead of applying a generic chart template.
- Use `../../references/foundations/meaning-preserving-visual-design-workflow.md` and `../../references/foundations/mobile-first-responsive-visualization.md` for concept generation, large-screen/mobile variants, approval gates, semantic contracts, mobile reading paths, touch/keyboard behavior, spotty-connection plans, and capability audits.
- Use annotations to explain turning points, mechanisms, caveats, and consequences.
- Prefer direct labels, small multiples, and focused panels over legends and equal-weight dashboards.
- Use restrained color: neutral context plus one or two intentional accents.
- Include a mobile/narrow version or adaptation rule whenever the output is for web.

Use `../../references/foundations/art-directed-interactive-visual-stories.md` when the user asks for a visually stunning interactive, animation, image generation, WebGL, particles, 3D, illustrated explanation, map-flow story, cutaway, object-based infographic, or anything inspired by major publication visual storytelling.

- Decide what the visual artifact is, not just what chart type it is.
- Treat references as principle studies. Write what was learned, then transform it into a story-specific composition that would not be mistaken for the reference.
- If the answer is imagery or illustration, state what the asset explains and which data layers stay editable.
- If the answer is animation, name the animation verb and provide a reduced-motion fallback.
- If the answer is particles or flow animation, state what one particle represents, what it must not imply, and how the static fallback preserves the claim.
- If the answer is 3D, state which data dimensions justify depth and what the static fallback is.
- If the answer is scrollytelling or parallax, use `../scrollytelling-and-parallax-data-visualization/SKILL.md`, outline the scenes, state what each reveal adds, and decide whether a stepper, small multiples, or static frames would be clearer.
- Add a human visual-review pass: would an editor keep the image, motion, labels, and pacing after novelty fades?

Use `../../references/foundations/fictional-data-story-simulation.md` when the story is invented or simulated.

- Build the simulated-world contract before choosing charts, imagery, animation, or interaction.
- Make sure the data can support multiple visual forms: temporal, spatial or physical, event, outcome, and derived comparison views.
- Label values as fictional or simulated and preserve the seed/regeneration path.
- Treat sparse fictional data as a design blocker, not a copywriting problem.

Use `../../references/foundations/sensitive-geopolitical-and-humanitarian-stories.md` when the story involves conflict, occupation, territorial control, civilian harm, displacement, disaster, sanctions, migration, or humanitarian need.

- Build a source and method ledger before sketching the layout.
- Distinguish measured, estimated, and schematic evidence layers in data, labels, and visual styling.
- Keep dates, source notes, attribution, and caveats close to the map states or human-impact values they support.
- Use humane, precise language and avoid decorative violence, team-color framing, or false precision.
- Require a static screenshot or export path that preserves the claim without hover, autoplay, or tactical-map interaction.

## Layout and Interaction Defaults

- Make one question dominant on the surface instead of giving equal emphasis to every chart, card, and control.
- Put legends, filters, toggles, and summaries next to the evidence they affect.
- Use direct labels, embedded keys, and short framing text before resorting to explanatory sidebars or long captions.
- Use domain-native backgrounds only when they add meaning or orientation. If used, keep them visually subordinate and let them inform mark placement, zones, or interaction.
- Use generated images only when they add meaning or orientation. Keep numerical labels and source notes in editable data-bound layers wherever possible, and enforce approved concepts through the shared semantic design contract.
- Use motion as staged explanation, not ambient decoration.
- Use scrollytelling when a linear author-led path helps readers understand staged change. Use a stepper when discrete states, replay, direct access, or known length matter more than scrolling.
- Use WebGL only when scale, interaction, particles, flow, shader effects, or true 3D make the renderer meaningfully better than SVG/DOM or Canvas2D.
- For operational workspaces, keep the main evidence viewport dominant. Use compact rails, command bars, navigation trees, drawers, synchronized inspectors, and active-state summaries instead of stacked card grids.
- Use particles only for flow, direction, accumulation, recency, focus, anomaly, risk, or state. Avoid particles as texture.
- Use hover for preview and selection for commitment; keep essential values and categories visible without pointer precision.
- Use touch-first mobile paths: tap or focus for inspection, step-through controls for dense targets, drag alternatives, explicit pinch/zoom ownership, and no hover-only evidence.
- Add reset paths and obvious escape hatches whenever interaction changes the analytical state.
- For ambitious interactive scenes, define the interaction state machine before coding: default, hover/preview, selected/committed, expanded/detail, paused/idle, loading, fallback, and error states as relevant.

## Chart Selection Heuristics

- Use bars, dots, and tables with in-cell graphics, including sparklines, for precise comparisons across categories.
- Use lines, horizon-like summaries, or small multiples for time and repeated temporal comparison.
- Use Gantt charts for planned schedules where task spans, milestones, dependencies, baselines, critical path, or resources are the main evidence. Prefer milestone timelines, Kanban boards, tables, dependency graphs, calendars, resource timelines, or uncertainty views when those better match the decision.
- Use UML, C4, ERD, BPMN, flowcharts, swimlanes, state machines, sequence diagrams, or dependency diagrams when system relationships, behavior, process, or architecture are the evidence.
- Use scatterplots, density views, and faceted alternatives for relationships and multivariate structure.
- Use histograms, box plots, violin plots, and interval-aware charts for distributions and uncertainty.
- Use maps only when geography is analytically meaningful.
- Use networks, trees, sankeys, or alluvial forms only when structure or flow is the story and simpler alternatives fail.
- Use 3D only when depth or volume is intrinsic to the data.
- Use WebGL-accelerated 2D when density, zoom/pan, GPU picking, particles, shader effects, or smooth animation materially improve analysis.

## Critique Checklist

1. Does the title state a question, claim, or purpose?
2. Is the key comparison assigned the strongest visual encoding?
3. Are scales, baselines, and units trustworthy?
4. Are aggregation, smoothing, uncertainty, and missingness disclosed?
5. Is color semantic or merely decorative?
6. Is the reading order obvious without reading a block of explanatory prose?
7. Can the viewer decode series or symbol meaning without chasing a detached legend?
8. Would direct labels, embedded keys, or small multiples outperform the current composition?
9. Is any interaction hiding something that should be visible immediately?
10. Does the visualization help the viewer decide what matters next?
11. Would the figure still make sense as a static screenshot without hover?
12. Does the mobile reading order preserve the same claim?
13. Does the mobile default view keep the main visualization visible rather than stacking controls first?
14. Are touch, pinch, on-screen keyboard, spotty connection, and permission-gated capability paths accounted for?
15. For operational workspaces, do the outline, filters, visualization, selected state, and inspector stay synchronized across desktop and mobile?
16. Does imagery, illustration, WebGL, particles, 3D, or animation carry analytical meaning?
17. Would the composition still work as a still screenshot?
18. Does the result look edited by a human rather than assembled from equal-weight chart boxes?
19. If generated concepts were used, did the user approve the large-screen and mobile concept set before project changes or implementation code began, and does the implementation preserve the approved semantic design contract, locked elements, and visual composition?
20. For sensitive stories, can a reader tell what is measured, estimated, schematic, disputed, or dated?
21. For composite deliverables, did each embedded chart, map, table-graphic, swarm, distribution, flow layer, particle layer, media overlay, or key get a specialist mini-brief and visible specialist guidance before integration?
22. For advanced interactive work, are renderer ownership, coordinate alignment, visual-effect meanings, picking, fallback rendering, and interaction states documented before implementation?

## Anti-Patterns

- 3D bars, tilted pies, and perspective distortion
- dual axes without extremely careful explanation
- rainbow ramps for ordered magnitude
- dashboards made of equally weighted KPI tiles
- decorative gradients, shadows, and animation that compete with the data
- particle effects, glows, fire, sparkles, or ambient motion that attract attention without explaining evidence
- generated backgrounds with ordinary charts pasted on top
- decorative parallax, scrolljacking, or scroll-scrubbed effects that make the reader fight the browser
- chart galleries masquerading as editorial stories
- contextual backgrounds used as wallpaper without changing interpretation, layout, or orientation
- map-first thinking for non-spatial questions
- interaction used to compensate for a weak default view
- explanatory paragraphs embedded in the chart chrome because the layout is doing too little work
- tooltips used as the primary key or as the only place important values appear

## What Good Looks Like

- The chart answers a concrete question.
- The dominant comparison is visually obvious.
- Supporting context is present but subordinate.
- Any contextual surface is accurate enough for the claim and helps the viewer understand where, how, or why the data occurs.
- Labels and keys stay with the evidence instead of living in a distant legend block.
- Annotation adds meaning, not clutter.
- The layout tells the viewer where to look first and what controls matter.
- The figure survives export, grayscale, resizing, and partial reproduction.
- The implementation approach still looks reasonable when the view is repeated across the actual product surface.

## References

- Shared theory:
  - `../../references/foundations/editorial-infographic-system.md`
  - `../../references/foundations/art-directed-interactive-visual-stories.md`
  - `../../references/foundations/meaning-preserving-visual-design-workflow.md`
  - `../../references/foundations/embedded-visualization-self-use.md`
  - `../../references/foundations/fictional-data-story-simulation.md`
  - `../../references/foundations/sensitive-geopolitical-and-humanitarian-stories.md`
  - `../../references/foundations/theory-and-principles.md`
  - `../../references/foundations/task-abstraction-and-chart-selection.md`
  - `../../references/foundations/mobile-first-responsive-visualization.md`
  - `../../references/foundations/operational-visualization-workspaces.md`
  - `../../references/foundations/domain-contextual-surfaces.md`
  - `../../references/foundations/storytelling-annotation-and-critique.md`
  - `../../references/foundations/layout-hierarchy-and-self-explanatory-ux.md`
  - `../../references/foundations/interaction-models-and-progressive-disclosure.md`
  - `../../references/foundations/implementation-design-and-tradeoffs.md`
- Templates:
  - `../../assets/templates/advanced-interactive-visualization-contract.md`
- Skill references:
  - `../gantt-chart-visualization/SKILL.md`
  - `../uml-and-software-architecture-visualization/SKILL.md`
  - `../scrollytelling-and-parallax-data-visualization/SKILL.md`
  - `./references/decision-framing.md`
  - `./references/chart-selection-patterns.md`
  - `./references/critique-lenses.md`
  - `./references/tufte-munzner-cairo-synthesis.md`

## Representative Prompts

- "What visualization should I use for this product analytics question?"
- "Help me visually design this visualization page and generate large-screen and mobile concept images."
- "Critique this chart and tell me the biggest reasoning failures."
- "Should this be a heatmap, dot plot, or small-multiple line chart?"
- "Would this visualization be clearer on a field, court, track, floor plan, or schematic background?"
- "Should this table use sparklines, bars, or standalone charts?"
- "Should this project schedule be a Gantt chart, roadmap, Kanban board, calendar, resource timeline, or dependency graph?"
- "How should I visualize MS Project, Primavera, Jira, GitHub Projects, Smartsheet, monday.com, Asana, ClickUp, or Azure DevOps planning data?"
- "Should this system explanation be a UML diagram, C4 view, ERD, BPMN workflow, flowchart, swimlane, state machine, sequence diagram, or dependency graph?"
- "I need a narrative figure for an executive audience, not a dashboard."
- "Should this be a scrollytelling story, parallax timeline, stepper, or small multiples?"
- "Explain why this visualization feels misleading even though the numbers are correct."

Referenced files: 5