Public-ready repository skill

Web data visualization

Integrates source-grounded editorial or scientific visualizations into existing web surfaces with semantic companions and coherent view state. Applies to static charts, SVG galleries, and coordinated interactive views whose delivery, responsive behavior, or export affects interpretation.

What this produces

An integrated, inspectable figure or view family with usable static reading, intentional enhancement, and evidence for the changed behavior.

Source and version

Repository path
.agents/skills/web-data-visualization/SKILL.md
Source revision
c1e35fdd57c2193812c2b183955aca15a5020be8
Source SHA-256
9535cf8e5b5e2589d4e93eb9b44bd528a71272b07d0537db456879c7691e402a
Publication standing
Public ready

Included source files

Complete skill source

The Markdown below matches the exact source text. The format link above opens the file on its own.

---
name: web-data-visualization
description: Integrates source-grounded editorial or scientific visualizations into existing web surfaces with semantic companions and coherent view state. Applies to static charts, SVG galleries, and coordinated interactive views whose delivery, responsive behavior, or export affects interpretation.
---

# Web data visualization

## Contract

- **What:** A web visualization whose source, visual grammar, state, semantic companion, and portable output form one coherent reader surface.
- **When:** A website or digital instrument needs a new or materially revised static figure, scientific plot, gallery, or coordinated set of views.
- **Boundaries:** The receiving repository owns styles, source generation, state, and publication. Source definitions and domain judgment retain authority over interpretation. Reuse precedes additional dependencies; a library or renderer enters for a demonstrated task need. Current delivery choices remain with the user.
- **Result:** An integrated, inspectable figure or view family with usable static reading, intentional enhancement, and evidence for the changed behavior.

## Fit and attention

- **Useful when:** A chart must work in an existing page, a cohort survives view changes, or SVG/table/export agreement matters.
- **Poor fit when:** A conversational sketch is sufficient, a PDF is the final receiver, or an unadmitted data source needs foundation work first.
- **Smallest useful dose:** One question-led figure, existing page styles, a full-size route, and a semantic value companion.
- **Foregrounds:** Source ownership, delivery mode, progressive enhancement, responsive reading, and synchronized meaning.
- **May under-attend:** Rendering and state checks leave domain validity and real assistive-technology use as separate claims.
- **Interactions:** [Data visualization foundations](../data-visualization-foundations/SKILL.md) establishes the meaning contract. Existing table, CSS-ownership, embedded-layout, stateful-behavior, and visual-verification skills receive only their changed boundaries. This skill retains the delivered web result.
- **Rest or release when:** The named reader operation works through the admitted modes, or an explicit dependency/question defines the next receiver.

## Inputs, defaults and output

Read the page as a visitor surface and locate its canonical data, renderer, styles,
assets, table inventory, and existing observations before choosing edits. Reuse
the page's actual visual owners, not merely a similar palette. Editorial and
scientific describe communication needs; Python, D3, or vanilla JavaScript
describe implementation choices. Any of them can produce a source-grounded
static figure.

The default is native semantic HTML with a static SVG and value companion. Native
HTML controls plus inline SVG fit coordinated interaction. Existing frameworks
remain valid within an established application. The return names changed reader
ability, owners, observations, remaining scope, and review/publication state.

## Rules

### Rule: Existing visual ownership is the first implementation path

Use the receiving page's type scale, spacing, table wrappers, caption, figure,
navigation, and full-view patterns. A new style requires an observable gap and a
clear owner/consumer. Read internal SVG paints and host CSS separately: a flat
SVG can still inherit a shadowed wrapper. For the Atlas series, quantitative
marks, labels, frame, and selected wrappers remain flat; unrelated site styling
retains its own contract.

### Rule: Delivery mode follows the required behavior

A static image resource works well for a cacheable standalone figure and full-size
link. Inline SVG exposes marks for styling, state, and interaction. The image
carrier retains external alt text and a semantic companion; controls inside an
image-delivered SVG supply no host-page interaction. Keep purely decorative SVG
out of the meaningful reading route. A standalone interactive SVG is a separate
delivery and accessibility decision, rather than an incidental export option.

### Rule: Population, operation, and presentation are distinct state

Keep population filters separate from the cognitive move and chart form. A valid
selected population and record persist through compatible view changes. A change
updates heading, units, legend, marks, summary, exact values, and portable state
from one accepted model. Empty or incompatible selections receive a named state
and a recovery route. Use native form controls for filters and actual tab semantics
only for tab panels with the corresponding keyboard behavior.

### Rule: Static reading remains a useful artifact

Author a meaningful baseline and evidence companion before enhancement. The
static figure and table answer the initial question when scripting is absent.
Controls enter with their enhancement and announce usable state concisely.
Visible copy describes the data and affordances rather than the construction
history. Captions, links, and tables remain available outside transient hover.

### Rule: SVG has one geometry and a recoverable subject

Use a root viewBox, deliberately grouped marks and labels, unique document-wide
IDs, native text, a meaningful name/description, and source context matching the
visible reading. Coordinate measurements share the mark's space. Batch geometry
reads before writes. Preserve required IDs, relationships, labels, and metadata
through export and optimization; source structure alone establishes neither
legibility nor universal AI interpretation.

### Rule: Dense data receives space and an exact-value route

Choose overview/detail, common-scale small multiples, or a matrix for the reader's
operation. Keep matrix bins, row/column identities, units, normalization, color
scale, and absence explicit. Allow named local scrolling and full-size access
instead of compressing labels beyond useful size. Hundreds of marks need not
be hundreds of Tab stops: native selectors and a persistent detail/table route
can supply precise access. A richer grid-navigation pattern needs its own task.

### Rule: Shared derivation has one owner

Pure transformations prepare detached derived state for visual, table, summary,
and export consumers. Escape text for the destination context; own-field admission
and bounded size precede use of external records. Reuse reviewed helpers rather
than duplicating their internals. Explain costs in terms of records, groups,
marks, and label work; a universal SVG-to-Canvas threshold remains unspecified
until measured in the receiving environment.

### Rule: Observation follows source and state settlement

Start with meaningful independent fixtures for quantities, absence, and state
transitions. Review the source before the affected-family browser pass. Then
observe actual container widths, full-size links, keyboard/focus, text visibility,
relevant alternate modes, and visible/table/export agreement. Renew affected
cases after repairs while preserving the scope of completed observations. A
documentation-only change normally leaves browser campaigns at rest.

## Operating sequence

1. **Locate:** Read the page, material owners, existing skills, and fitting family harness.
2. **Admit:** Apply the foundation and settle the selected view's source/measure contract.
3. **Compose:** Reuse the existing static figure, caption, table, and full-size patterns; choose only the necessary enhancement.
4. **Bind:** Share accepted state and derivation across controls, marks, summaries, exact values, and downloads.
5. **Observe:** Use small fixtures and independent review, then the focused rendered journey whose claim changed.
6. **Deliver:** Return a reviewable repository change and one evidence summary; hosted release follows its separate authority and carrier.

## Decisive scenarios

### Scenario: A selected cohort changes visual form

- **Given:** A visitor selected one product type and a record/detail in a comparison view.
- **When:** The visitor chooses a compatible reconciliation view.
- **Then:** The cohort persists, the selected detail persists where meaningful, and title, denominator, exact values, and exported state describe that same selection.

### Scenario: A large heatmap reaches an embedded surface

- **Given:** Matrix labels are readable standalone but become cramped in the actual iframe.
- **When:** The embedded route is composed.
- **Then:** Local scroll, an overview, or full-size access preserves readable values; the surrounding page continues to reflow and the child width is measured.

## Strain and recovery

New CSS multiplying familiar patterns, a chart-specific copy of shared math, or
repeated broad campaigns signals a return to the owner and changed claim.
Preserve accepted state and static reading. A smaller admitted view can ship
while a separately named interaction or performance experiment remains gated.

## Conditional context

- Load [SVG and coordinated views](references/svg-and-coordinated-views.md) for SVG delivery, multiview state, dense matrices, export, or Probe application.
- Load the foundation's [evidence map](../data-visualization-foundations/references/evidence-and-source-map.md) for research-backed design claims and current technical anchors.
- Load [Atlas exercises](../data-visualization-foundations/references/atlas-exercises.md)
  during a coordinated Atlas view and its related gallery or public-extract
  gates.

## Completion and re-entry

The intended reader can find the figure, perform the operation, recover values,
and retain meaning through the supported state and delivery modes. Evidence
names the source and states covered. A new dataset, view, container, interaction,
or receiving consumer reopens the corresponding boundary. Public-ready source
and hosted publication remain separately governed states.

## Conditional interpretation boundaries on web surfaces

Use the foundation's [sparse-time and scale guide](../data-visualization-foundations/references/sparse-time-scales-and-form-boundaries.md)
and [aggregation, distribution, and uncertainty guide](../data-visualization-foundations/references/aggregation-distribution-and-uncertainty.md)
when those meanings enter an editorial or scientific view. The renderer and
library remain implementation choices; the same data contract applies to
hand-authored SVG, generated static figures, and coordinated views.

A filter, normalization, bin-width, or scale control changes an explicit piece
of view state. Name whether the action highlights existing marks or changes the
eligible population and denominator. Derive the chart, native table, caption,
and export from the same accepted state. Keep bin edges and comparison domains
stable when stability serves comparison; expose any intentional recomputation.
Axes and legends receive the same updated mapping as the marks.

Keep isolated observations, gaps, bounds, and uncertainty available through the
visible surface and its persistent value companion. Clipping, aggregation, or
level-of-detail reduction has a named meaning and a route to the retained data.
A hidden mark, tooltip, or color distinction alone leaves that meaning fragile.
When suppression applies, selected detail, totals, and downloads share its
approved disclosure boundary.

Choose focused behavior evidence from the changed contract: for example, a
selection changing its denominator, a singleton beside a gap, or a scale toggle
with a zero-valued record. A new statistical interpretation can be settled in
source before browser work; a changed visual or interaction receives the
smallest existing affected-view check.