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 m

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

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 redra

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

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, rem

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

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 visual

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

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 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

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:
  

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.

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 landsca

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 10 — file references are metadata, not package contents.

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 — file references are metadata, not package contents.

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 sta

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

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 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

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, sli

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

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 vis

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

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 — file references are metadata, not package contents.

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

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.

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 comma

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 9 — file references are metadata, not package contents.

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 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

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:
   - s

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

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 vari

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.