Ships accessible charts: real text alternatives, keyboard focus, stable server rendering and color-safe encodings.
$ npx skills add https://craftwork.design/skills/accessible-charts -a claude-code -y
Installs into .claude/skills/accessible-charts. Add -g for every project.
SKILL.md
Ship Accessible Charts
Run trigger → inspect → decide → build → verify before release. A chart is shipped only when its semantic alternative, adapter lifecycle, SSR policy, renderer, exports, package boundaries, and teardown are proven in a consumer-shaped scenario.
Accessibility Checks
Check: the name identifies the comparison
Expected:
const hostOptions = {
definition,
height: 320,
initialWidth: 640,
ariaLabel: 'Weekly downloads for Core and React packages',
ariaDescription: 'Values are seven-day totals. Missing weeks appear as gaps.',
}
Fail condition: the label says only “chart”, repeats a visible heading without the metric, or omits the comparison and period.
Fix: name the metric, compared entities, and time scope; put conclusions and detailed values in normal application content.
Check: critical values have an equivalent representation
Expected: a visible heading and units, plus an adjacent summary or semantic table when precise values or application decisions depend on the chart.
Fail condition: the only way to retrieve an essential value is pointer hover, color, motion, or visual estimation.
Fix: bind the same semantic rows or selected key to application text/table controls.
Check: every interaction has a non-pointer path
Expected: native point keyboard navigation, semantic buttons/inputs for free cursors and range controls, visible focus, cancel/reset paths, and meaningful committed-state text.
Fail condition: a transparent pointer overlay is the sole control surface.
Fix: use first-party controls where their keyboard contract fits and application-owned semantic controls otherwise.
Lifecycle Checks
Check: SSR uses a supported adapter and deterministic inputs
Fail condition: definition construction reads browser layout, random values, local time, or unresolved async data; or the selected adapter does not promise SSR.
Fix: resolve data before render, use deterministic formatting and dimensions, and follow the selected adapter reference.
Check: mount, update, and cleanup stay adapter-owned
Expected: one runtime per mounted adapter instance, complete immutable option updates, stable definitions until captured values change, and cleanup on unmount/disconnect.
Fail condition: application code calls DOM measurement or mounts a browser host during server render, or retains observers/listeners after removal.
Fix: use the adapter lifecycle or mountChart only in a browser-owned mount phase and call destroy() at teardown.
Renderer and Export Checks
Check: renderer choice matches the task
SVG: visible server geometry, vector export, DOM styling, ordinary interactive charts.
Canvas: high scene counts or raster-first output; server emits an accessible shell, not pixels.
Static SVG: deterministic server/export artifact without browser interaction.
React Native SVG: explicit native target with device-level validation.
Check: export is reproducible
Expected: explicit dimensions, theme/background, scoped IDs, portable fonts/assets, intentional focus inclusion, and a meaningful exported name/description.
Fail condition: export depends on current responsive pixels or unreachable application CSS/resources.
Fix: render an explicit scene or serialize/rasterize with explicit artifact policy.
Common Mistakes
CRITICAL Using a generic accessible label
Wrong: ariaLabel: 'Chart'.
Correct: identify the metric, entities, period, and unit needed to understand the figure.
A generic label exposes a focusable graphic without useful identity.
Source: docs/guides/accessibility.md
HIGH Making the chart the only representation
Wrong: require hover or visual estimation for exact operational values.
Correct: render a summary, table, or application controls from the same semantic data/state.
The chart surface is supplemental when exact values are critical.
CRITICAL Mounting a browser host during server rendering
Wrong: call mountChart or adapter DOM mount from a server lifecycle.
Correct: prerender a deterministic scene through a supported SSR adapter or renderChartSvg, then mount the browser host only after a real element exists.
Measurement and mutation require browser elements. Older Angular workarounds were especially prone to this boundary error.
Focus, tooltip, keyboard, controls, cursors, and SVG animation belong to the reusable definition; adapters own surface lifecycle and framework body composition. The current definition API replaces legacy adapter behavior props.
Source: chart-behavior migration in CHANGELOG.md; React chart reference
HIGH Importing the universal barrel on native
Wrong: use @tanstack/charts/universal for every native chart.
Correct: use exact core mark/scale/scene and @tanstack/charts/react-native subpaths unless cross-platform authoring justifies the universal bundle.
Exact imports protect Metro and native declaration environments from unrelated browser and optional capability code.
HIGH Tension: rich interaction versus portable rendering
DOM convenience can break static SVG, Canvas, native, SSR, or keyboard equivalence. Keep semantics in definitions and application state; use platform-specific body/host extensions only at the presentation seam.
See also: build-chart-interactions/SKILL.md and extend-tanstack-charts/SKILL.md
Pre-Deploy Summary
Meaningful name and concise description.
Visible units, time range, and source context.
Exact-value summary/table where required.
Pointer, keyboard, touch, and cancel/reset scenarios.
Reduced-motion and non-color evidence.
Supported SSR policy with deterministic initial geometry.
Stable definition, mark, datum, and resource IDs.
Mount, update, resize, font relayout, and destroy verified.
Renderer and export behavior verified from a packed consumer.
Native claims verified on target devices when applicable.
