d3-visualization

Build deterministic, verifiable data visualizations with D3.js (v6). Generate standalone HTML/SVG (and optional PNG) from local data files without external n...

Security Scan

The skill appears to do what it says — produce deterministic D3 visualizations from local data — with only minor inconsistencies (notably a D3 version mismatch and no provided vendoring/install steps).

Purpose & Capability

The files and instructions align with a D3 visualization helper: example charts, tooltip handlers, and rules for deterministic output. Minor inconsistency: the top-level description mentions D3 v6 while the SKILL.md and recommended vendor filename pin d3 v7.9.0.

Instruction Scope

SKILL.md confines actions to reading local data files (*.csv, *.tsv, *.json), producing static output under dist/, and vendoring D3 locally (explicitly forbids CDNs). It does not instruct reading unrelated system files, exfiltrating data, or accessing credentials.

Install Mechanism

This is instruction-only (no install spec), which is low-risk. However SKILL.md expects a vendored D3 bundle (vendor/d3.v7.9.0.min.js) but provides no automated install or vendor file — the operator/agent must supply it or bundle the dependency manually.

Credentials

No environment variables, secrets, or external credentials are requested or required; the scope is proportionate to producing offline visualizations.

Persistence & Privilege

The skill is not always-enabled and has no special persistence or elevated privileges. It does not modify other skills or system-wide settings.

Assessment

This skill is generally coherent for generating deterministic D3 visualizations from local data, but consider the following before installing/using: 1) D3 version mismatch — the metadata mentions v6 while SKILL.md pins v7.9.0; confirm which version you want and ensure example code is compatible. 2) No install/vendoring steps are provided — SKILL.md expects you to vendor d3 (vendor/d3.v7.9.0.min.js) or bundle it with a lockfile; make sure the required D3 file is supplied locally (the skill forbids CDNs). 3) Example code fetches data via relative paths (e.g., /data/stocks.csv) — verify your deployment will serve those files over HTTP or adapt the code to inline data. 4) Force-directed layouts can be non-deterministic unless you follow the given determinism rules; review the examples (they use forceSimulation) and test reproducibility. 5) There are no network exfiltration patterns in the files, but if you plan to run the skill in an environment with sensitive local files, ensure only intended data files are used. If you want higher confidence, ask the author to: (a) resolve the D3 version inconsistency, (b) include an explicit vendoring/install step or bundled vendor file, and (c) confirm the intended data file paths and hosting model.

D3.js Visualization Skill

Use this skill to turn structured data (CSV/TSV/JSON) into clean, reproducible visualizations using D3.js. The goal is to produce stable outputs that can be verified by diffing files or hashing.

When to use

Activate this skill when the user asks for any of the following:

• “Make a chart/plot/graph/visualization”
• bar/line/scatter/area/histogram/box/violin/heatmap
• timelines, small multiples, faceting
• axis ticks, scales, legends, tooltips
• data-driven SVG output for a report or web page
• converting data to a static SVG or HTML visualization

If the user only needs a quick table or summary, don’t use D3—use a spreadsheet or plain markdown instead.

---

Inputs you should expect

• One or more local data files: *.csv, *.tsv, *.json
• A chart intent:
  • chart type (or you infer the best type)
  • x/y fields and aggregation rules
  • sorting/filtering rules
  • dimensions (width/height) and margins
  • color rules (categorical / sequential)
  • any labeling requirements (title, axis labels, units)
• Output constraints:
  • “static only”, “no animation”, “must be deterministic”, “offline”, etc.

If details are missing, make reasonable defaults and document them in comments near the top of the output file.

---

Outputs you should produce

Prefer producing all of the following when feasible:

1. dist/chart.html — standalone HTML that renders the visualization
2. dist/chart.svg — exported SVG (stable and diff-friendly)
3. (Optional) dist/chart.png — if the task explicitly needs a raster image

Always keep outputs in a predictable folder (default: dist/), unless the task specifies paths.

---

Determinism rules (non-negotiable)

To keep results stable across runs and machines:

Data determinism

• Sort input rows deterministically before binding to marks (e.g., by x then by category).
• Use stable grouping order (explicit Array.from(grouped.keys()).sort()).
• Avoid locale-dependent formatting unless fixed (use d3.format, d3.timeFormat with explicit formats).

Rendering determinism

• No randomness: do not use Math.random() or d3-random.
• No transitions/animations by default (transitions can introduce timing variance).
• Fixed width, height, margin, viewBox.
• Use explicit tick counts only when needed; otherwise rely on D3 defaults but keep domains fixed.
• Avoid layout algorithms with non-deterministic iteration unless you control seeds/iterations (e.g., force simulation). If a force layout is required:
  • fix the tick count,
  • fix initial positions deterministically (e.g., sorted nodes placed on a grid),
  • run exactly N ticks and stop.

Offline + dependency determinism

• Do not load D3 from a CDN.
• Pin D3 to a specific version (default: d3@7.9.0).
• Prefer vendoring a minified D3 bundle (e.g., vendor/d3.v7.9.0.min.js) or bundling with a lockfile.

File determinism

• Stable SVG output:
  • Avoid auto-generated IDs that may change.
  • If you must use IDs (clipPath, gradients), derive them from stable strings (e.g., "clip-plot").
• Use LF line endings.
• Keep numeric precision consistent (e.g., round to 2–4 decimals if needed).

---

Recommended project layout

If the task doesn't specify an existing structure, use:

dist/
  chart.html        # standalone HTML with inline or linked JS/CSS
  chart.svg         # exported SVG (optional but nice)
  chart.png         # rasterized (optional)
vendor/
  d3.v7.9.0.min.js  # pinned D3 library

---

Interactive features (tooltips, click handlers, hover effects)

When the task requires interactivity (e.g., tooltips on hover, click to highlight):

Tooltip pattern (recommended)

1. Create a tooltip element in HTML:

<div id="tooltip" class="tooltip"></div>

2. Style with CSS using .visible class for show/hide:

.tooltip {
    position: absolute;
    padding: 10px;
    background: rgba(0, 0, 0, 0.8);
    color: white;
    border-radius: 4px;
    pointer-events: none;  /* Prevent mouse interference */
    opacity: 0;
    transition: opacity 0.2s;
    z-index: 1000;
}

.tooltip.visible {
    opacity: 1;  /* Show when .visible class is added */
}

3. Add event handlers to SVG elements:

svg.selectAll('circle')
    .on('mouseover', function(event, d) {
        d3.select('#tooltip')
            .classed('visible', true)  // Add .visible class
            .html(`<strong>${d.name}</strong><br/>${d.value}`)
            .style('left', (event.pageX + 10) + 'px')
            .style('top', (event.pageY - 10) + 'px');
    })
    .on('mouseout', function() {
        d3.select('#tooltip').classed('visible', false);  // Remove .visible class
    });

Key points:

• Use opacity: 0 by default (not display: none) for smooth transitions
• Use .classed('visible', true/false) to toggle visibility
• pointer-events: none prevents tooltip from blocking mouse events
• Position tooltip relative to mouse with event.pageX/pageY

Click handlers for selection/highlighting

// Add 'selected' class on click
svg.selectAll('.bar')
    .on('click', function(event, d) {
        // Remove previous selection
        d3.selectAll('.bar').classed('selected', false);
        // Add to clicked element
        d3.select(this).classed('selected', true);
    });

CSS for highlighting:

.bar.selected {
    stroke: #000;
    stroke-width: 3px;
}

Conditional interactivity

Sometimes only certain elements should be interactive:

.on('mouseover', function(event, d) {
    // Example: Don't show tooltip for certain categories
    if (d.category === 'excluded') {
        return;  // Exit early, no tooltip
    }
    // Show tooltip for others
    showTooltip(event, d);
})

---