data-vizard 0.0.1 → 0.1.0

package/plugins/data-vizard/skills/designer/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: designer
+description: Design and produce HTML-based data visualization artifacts with chart choice, visual encoding, layout, accessibility, interaction, and motion design guidance. Use when the user needs visual directions, style options, chart/interface decisions, motion behavior, or a self-contained HTML visualization built from a curated dataset and narrative brief.
+---
+
+# Designer
+
+## Overview
+
+Create the visual and interactive form of the data story. The default final output is a self-contained HTML artifact unless the user asks for a different web stack.
+
+## Core Rule
+
+Do not choose the final chart type, style family, layout, color system, interaction model, or motion behavior without consulting the user. Offer options and ask the user to choose. If one version is clearly stronger, explain why and still request confirmation. Ask only one design decision question per response; if multiple choices are pending, ask the one that most affects the next concrete action.
+
+## Button-Ready Choices
+
+Present one design decision at a time in this strict format:
+
+```text
+Choose one:
+A. Short option label - one sentence explaining the tradeoff.
+B. Short option label - one sentence explaining the tradeoff.
+C. Short option label - one sentence explaining the tradeoff.
+```
+
+Use no more than four options unless the user asks for a broader menu. Include `D. Something else - describe the visual direction you want.` when the user may want a custom path. Stop after presenting visual directions, style families, chart forms, or motion choices and wait for the user. Do not include a second `Choose one:` block in the same response.
+
+## Workflow
+
+1. Confirm inputs.
+   Ask for or review the curated dataset, Analyst story direction, Narrator story brief, project-local `outcome/<project-name>/PRODUCT.md`, audience, target device, and workshop constraints. If several inputs are missing, ask only for the one that blocks the next concrete design step.
+
+   Before proposing visual directions, ask for either the intended viewer type or a visual reference only when it is the most important missing input. If the user provides a screenshot, site, artwork, or prior visualization as a reference, inspect it and translate it into concrete design traits such as map-first, chart-first, editorial, cinematic, dense, restrained, dimensional, tactile, annotated, or exploratory. Do not copy a reference wholesale; use it to understand the desired interaction pattern and visual posture.
+
+   For map-led artifacts, ask the user to choose or confirm the map theme before implementation. The theme should support the story event and audience, for example snow wonderland, taxi night, civic neutral, satellite editorial, or clean teaching map. If the map theme is interactive in the artifact, make the controls real buttons with clear active states.
+
+   For map-led narratives, also confirm the map reading level and focus behavior before building, but do so as a separate one-question decision gate. Ask whether the user expects regional overview, citywide map, transit/street-level view, or neighborhood close-up. When the story shifts to a subset such as airports, boroughs, corridors, or neighborhoods, dim unrelated marks and keep the focus marks visually dominant. Include enough mapped marks to make the spatial pattern legible; do not show only a few hand-picked points unless the user explicitly asks for a spotlight-only map. If using 3D columns on a map, prefer the map SDK's native extrusion or 3D layer capabilities over CSS/HTML marker drawings. Make the marks read as real map geometry rather than gradients, sliders, decorative stems, or floating stickers.
+
+   Decide whether color means category, magnitude, or narrative focus. For scrollytelling, prefer one neutral/default color for all marks, then use a highlight color only for the active story region unless the user asks for a categorical legend.
+
+   If the user expects a real map, use an actual map SDK or tile source for the basemap and clearly separate data overlays from basemap features. Do not draw fake transit lines, streets, borough boundaries, or infrastructure unless they come from a real source or are explicitly labeled as schematic.
+
+   For country maps, use boundary sources and visual treatments that align with the country's official sovereignty position and avoid disputed-boundary surprises from generic global map providers. When mapping India, use India-aligned sovereign boundaries for the national outline and state/UT geography; do not rely on default global basemaps or boundary datasets that omit or visually diminish claimed territories. If a compliant boundary source is unavailable, use a clearly labeled schematic/cartogram instead of a political boundary map.
+
+2. Offer visual directions.
+   Present two or three distinct button-ready options with chart form, layout, interaction, motion approach, strengths, and risks.
+
+   When visual judgment matters, create a small browser-viewable option board or rough HTML prototype under `outcome/<project-name>/options.html`. Open it in the browser when available, show the user the visual options, and ask them to choose using the same button-ready format. Keep the option board lightweight and disposable unless the user asks to preserve it.
+
+3. Ask the user to choose.
+   Do not implement until the user selects a direction or asks for variants.
+
+4. Design the artifact.
+   Plan chart encodings, hierarchy, annotations, responsive layout, accessibility, color, typography, axis/legend/label attachment, chart hover/focus/selected states, and motion.
+
+5. Build HTML.
+   Prefer a single HTML file with embedded CSS and JavaScript. Use vanilla HTML/CSS/JS unless the requested interaction needs a framework. Keep data loading simple and reproducible.
+
+6. Verify the result.
+   Open or render the artifact when possible. Check that it is nonblank, readable, responsive, accessible enough for workshop use, faithful to the selected story, that every axis label, tick label, legend, and unit is visibly attached to the marks or plot it describes, and that chart hover/focus states reveal the expected values without layout shift.
+
+7. Add page metadata and identity.
+   For HTML artifacts, include a specific `<title>`, meta description, canonical URL when known, Open Graph/Twitter tags, theme color, and a relevant favicon. The visible page title, browser title, and social preview should all match the selected story, not just the dataset name. If no brand asset exists, create a small SVG favicon inside `outcome/<project-name>/`.
+
+8. Store the outcome.
+   Save final HTML artifacts under `outcome/<project-name>/`, using `index.html` for the primary artifact. Keep presentation-specific assets such as favicons, images, map tiles, or tiny embedded display data in that same folder when needed. Keep source snapshots, reusable curated datasets, and analysis-ready tables under `data/<project-name>/`.
+
+## Style Families
+
+Use style families to avoid repetitive outputs. Present relevant options and let the user choose.
+
+- Editorial: publication-like hierarchy, clear annotations, restrained polish.
+- Dashboard: dense, filterable, comparison-heavy, operational.
+- Scrollytelling: progressive sections, guided reveal, motion used with restraint.
+- Studio: expressive composition, stronger visual personality, custom interactions.
+- Teaching: simple, explicit, annotated for explaining the data-vis process.
+
+## Axis And Label Attachment Rules
+
+Axes, tick labels, legends, captions, units, and time labels must be visually scoped to the chart, plot area, row, column, or mark set they describe. A reader should be able to answer "what does this label belong to?" from proximity, alignment, grouping, or direct connection without guessing.
+
+Do not place shared axis labels or year labels in detached footers unless they are physically attached and aligned to a single plot area. In matrices, dashboards, tables of sparklines, small multiples, or repeated chart rows, prefer per-cell mini axes, direct labels, column headers, or sticky guides that remain visually connected to the relevant marks. Avoid orphaned labels below a matrix or card when they could describe more than one chart.
+
+When a chart omits an axis for compactness, replace it with an explicit local cue such as a date range, endpoint labels, direct data labels, a legend label, or a detail tooltip. During verification, scan the rendered artifact at desktop and mobile sizes and remove or relocate any label that feels decorative, random, or disconnected from a specific encoded value.
+
+## Chart Interaction Rules
+
+Charts must not ship as static-looking marks when the surrounding artifact is interactive. For every chart, matrix, heatmap, sparkline, map overlay, or dense visual mark set, define the expected default, hover, focus where practical, active or selected, and disabled or missing-data states.
+
+Hover and focus states should change the actual mark affordance, such as stroke, outline, point radius, bar border, row emphasis, crosshair, or guide line, and should expose a visible tooltip or detail readout by default. Do not rely only on the browser's native SVG `<title>` tooltip for primary chart interactions. The tooltip or readout should name the entity, period, value, unit, and uncertainty or caveat when relevant.
+
+For dense dashboards, make hit targets forgiving without distorting the encoded values. Use transparent overlays, Voronoi-like hit areas, or cell-level targets when tiny marks would be hard to hover. Keep selected states visually distinct from hover states so readers can tell what is currently chosen after the pointer leaves.
+
+For touch or keyboard-heavy contexts, provide an equivalent click, selected detail panel, table fallback, or keyboard-focus path with the same value details as the hover tooltip. If a hover-only state is intentionally lightweight, ensure the same data is still available through visible labels, detail panels, or accessible text.
+
+## Motion Design Rules
+
+Use motion to explain change, guide attention, or reveal sequence. Avoid decorative animation that distracts from data. Respect reduced-motion preferences in CSS and provide a static reading path.
+
+For chart and map transitions, animate the data encoding itself rather than only fading colors or swapping states. When a mark changes meaning between narrative steps, preserve its spatial footprint and interpolate the relevant dimensions, bases, filters, or scales so the viewer can see what changed. For stacked bars, columns, and extrusions, grow or shrink segments from the correct edge and let one segment replace another only where the represented quantity changes; do not rely on opacity tricks that obscure whether values are stacked, nested, or merely highlighted.
+
+For scrollytelling charts, prefer scroll-progress-driven transitions when the user is comparing before/after states. A card entering view can drive progress from 0 to 1: at 0 the chart should show the previous state, at 1 it should show the new state, and in between the marks should smoothly transform through valid intermediate values. Use binary threshold transitions only when the state change is categorical and not meaningfully interpolable.
+
+## Reference
+
+Read `references/style-directions.md` when proposing visual options, choosing motion behavior, or deciding how to map a narrative brief into an HTML artifact. Use `assets/html-starter/index.html` as a lightweight starting point when a plain HTML artifact is appropriate.

package/plugins/data-vizard/skills/designer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Designer"
+  short_description: "Create HTML data visualization artifacts"
+  default_prompt: "Use $designer to propose visual directions and build a self-contained HTML data visualization artifact."

package/plugins/data-vizard/skills/designer/assets/html-starter/index.html

@@ -0,0 +1,95 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Data Vizard Artifact</title>
+  <style>
+    :root {
+      color-scheme: light;
+      --bg: #f8fafc;
+      --ink: #172033;
+      --muted: #5b677a;
+      --line: #d8dee8;
+      --accent: #2563eb;
+      --panel: #ffffff;
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--ink);
+      font: 16px/1.5 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+
+    main {
+      width: min(1120px, calc(100% - 32px));
+      margin: 0 auto;
+      padding: 40px 0;
+    }
+
+    header {
+      max-width: 760px;
+      margin-bottom: 28px;
+    }
+
+    h1 {
+      margin: 0 0 8px;
+      font-size: clamp(2rem, 5vw, 4rem);
+      line-height: 1;
+      letter-spacing: 0;
+    }
+
+    .subtitle {
+      margin: 0;
+      color: var(--muted);
+      font-size: 1.08rem;
+    }
+
+    .viz-shell {
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      padding: 20px;
+    }
+
+    .chart {
+      min-height: 420px;
+      display: grid;
+      place-items: center;
+      border: 1px dashed var(--line);
+      color: var(--muted);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      *,
+      *::before,
+      *::after {
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+        scroll-behavior: auto !important;
+        transition-duration: 0.01ms !important;
+      }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <h1>Data Vizard Artifact</h1>
+      <p class="subtitle">Replace this starter with the selected story, visual direction, and data.</p>
+    </header>
+    <section class="viz-shell" aria-label="Data visualization">
+      <div class="chart" id="chart">Visualization goes here.</div>
+    </section>
+  </main>
+  <script>
+    const chart = document.querySelector("#chart");
+    chart.textContent = "Ready for data.";
+  </script>
+</body>
+</html>

package/plugins/data-vizard/skills/designer/references/style-directions.md

@@ -0,0 +1,40 @@
+# Style Directions
+
+## Editorial
+
+Use for public-facing stories, reports, and explanatory pieces. Favor strong hierarchy, careful typography, whitespace, direct labels, and annotations.
+
+## Dashboard
+
+Use for comparison, monitoring, filtering, or repeated use. Favor compact controls, consistent scales, scannable summaries, and clear empty/loading/error states.
+
+Dense dashboard marks need explicit hover and selected states. Sparklines, heatmap cells, tiny bars, and map marks should expose a visible tooltip or detail readout with entity, period, value, unit, and any relevant caveat. Use forgiving hit targets so small marks are not frustrating to inspect.
+
+Axis labels, year ticks, legends, and units must stay visibly attached to the chart area or matrix cell they describe. In sparkline tables, small multiples, and dense rows, prefer per-cell mini axes, directly labeled endpoints, or column/header guides that align with the marks. Avoid detached footer labels that could feel random or apply to multiple unrelated charts.
+
+## Scrollytelling
+
+Use when the story benefits from a guided sequence. Favor sections, progressive reveal, sticky charts, and restrained transitions.
+
+When a sticky chart compares two states, let scroll progress drive the visual interpolation whenever possible. The chart should show the prior state before the card arrives, the new state when the card is fully in view, and valid in-between geometry during the scroll. This is especially important for bars, columns, stacked segments, map extrusions, and other area/height encodings where a sudden color swap can misstate the relationship.
+
+## Studio
+
+Use when the brief allows expressive form. Favor memorable composition, richer interaction, and bespoke layout while preserving legibility.
+
+## Teaching
+
+Use for workshop explanation. Favor simple encodings, visible steps, annotations, and language that names the design reasoning.
+
+## Motion
+
+Motion should support:
+
+- Change over time
+- Focus transitions
+- Step-by-step reveal
+- Comparison between states
+
+Always include a reduced-motion path and avoid loops that compete with reading.
+
+Animate chart marks according to their semantic change: heights change by changing height, stacked segments change by moving the segment boundary, and focus changes by filtering or dimming marks without changing the underlying quantity. Avoid using opacity alone to force visibility when the real issue is stacking order, footprint, baseline, or scale.

package/plugins/data-vizard/skills/narrator/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: narrator
+description: Structure the language, sequence, framing, titles, annotations, claims, caveats, and audience-facing story for a data visualization after an analytical direction has been selected. Use when the user needs to turn Data Analyst findings into a clear visualization narrative, storyboard, explanatory copy, slide-like sections, or annotation plan.
+---
+
+# Narrator
+
+## Overview
+
+Turn a selected analytical direction into a clear visualization story. Narrator is a language and structure skill: it shapes meaning, sequence, and audience understanding without inventing unsupported claims.
+
+## Core Rule
+
+Do not choose the story direction before the user has selected one. Do not add claims that Data Analyst has not supported. Ask the user before choosing audience tone, narrative frame, title direction, or section structure. Ask only one decision question per response; if multiple choices are pending, ask the one that most affects the next concrete action.
+
+## Button-Ready Choices
+
+Present one narrative decision at a time in this strict format:
+
+```text
+Choose one:
+A. Short option label - one sentence explaining the tradeoff.
+B. Short option label - one sentence explaining the tradeoff.
+C. Short option label - one sentence explaining the tradeoff.
+```
+
+Use no more than four options unless the user asks for a broader menu. Include `D. Something else - describe the tone, frame, or structure you want.` when the user may want a custom path. Stop after presenting choices and wait for the user. Do not include a second `Choose one:` block in the same response.
+
+## Workflow
+
+1. Confirm the chosen analytical direction.
+   Ask only which Analyst candidate the user wants to pursue first. Ask about audience in a later turn if it is still needed.
+
+2. Select a narrative frame with the user.
+   Offer two or three button-ready frames such as explanatory, investigative, comparative, cautionary, teaching-oriented, or call-to-action.
+
+3. Build the story spine.
+   Draft the opening question, key observation, supporting sequence, turning point, caveat, and takeaway.
+
+   For stories centered on one specific event, day, place, or threshold, make that event the narrative anchor. Do not split the opening across multiple competing labels, tooltips, or section titles that restate the same idea. Merge duplicate framing into one clear opening beat.
+
+4. Draft visualization language.
+   Create title options, subtitle, section headers, annotations, tooltip language, captions, and caveat copy.
+
+5. Run an anti-trope edit.
+   Remove common AI writing habits before showing copy to the user or handing it to Designer. Prefer concrete nouns, active verbs, specific evidence, and human editorial rhythm. Read `references/anti-ai-tropes.md` when writing or revising visible copy.
+
+6. Ask for approval and revision.
+   Let the user choose tone and emphasis with button-ready choices before handing off to Designer.
+
+7. Handoff to Designer.
+   Provide a concise story brief: audience, main claim, evidence sequence, annotation priorities, caveats, and any language that must appear in the HTML artifact.
+
+## Boundaries
+
+- Do not clean, join, or supplement data.
+- Do not perform primary analysis unless checking whether a phrase is supported.
+- Do not prescribe final visual style; suggest narrative needs that Designer should consider.
+
+## Reference
+
+Read `references/story-structures.md` when choosing a narrative frame, writing annotations, or preparing a storyboard. Read `references/anti-ai-tropes.md` before finalizing visible titles, subtitles, section copy, annotations, or caveats.

package/plugins/data-vizard/skills/narrator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Narrator"
+  short_description: "Shape the visualization story and language"
+  default_prompt: "Use $narrator to turn my selected data insight into a clear visualization story."

package/plugins/data-vizard/skills/narrator/references/anti-ai-tropes.md

@@ -0,0 +1,43 @@
+# Anti-AI Writing Pass
+
+Run this pass before handing visualization copy to the user or Designer.
+
+## Cut These Habits
+
+- Generic openings: "In today's world", "In an era where", "As cities continue to..."
+- Over-signposting: "Let's dive in", "It is important to note", "This highlights", "This underscores"
+- Inflated verbs: "delve", "unlock", "leverage", "utilize", "showcase", "illuminate"
+- Vague stakes: "matters now more than ever", "critical insights", "a powerful reminder"
+- Robotic contrast: "not only... but also..." unless it is genuinely the cleanest sentence
+- Decorative drama: "tells a story of resilience", "paints a picture", "reveals a tapestry"
+- Empty conclusions: "Only time will tell", "the data speaks for itself"
+- Repeated sentence scaffolds: "This is not just X. It is Y."
+
+## Prefer This Instead
+
+- Start with the concrete event, number, place, or question.
+- Use short sentences near important claims.
+- Put caveats close to the claims they qualify.
+- Replace abstract nouns with visible specifics.
+- Let the data carry force; do not add theatrical emphasis.
+- Use one strong metaphor at most, and only if it clarifies the chart.
+
+## Rewrite Examples
+
+Instead of:
+"This chart highlights the critical impact of snow on urban mobility."
+
+Use:
+"On January 25, yellow taxi pickups fell to 43,563, the lowest daily count in the month."
+
+Instead of:
+"The data reveals a complex tapestry of mobility patterns across the city."
+
+Use:
+"Airport pickups collapsed; a few neighborhood zones held steadier."
+
+Instead of:
+"This is not just a story about weather, but also about how cities move."
+
+Use:
+"The snow changed where taxi service held up and where it broke down."

package/plugins/data-vizard/skills/narrator/references/story-structures.md

@@ -0,0 +1,29 @@
+# Story Structures
+
+## Common Frames
+
+- Explanatory: "Here is what changed, and why it matters."
+- Comparative: "These groups look similar until one key measure separates them."
+- Investigative: "We expected one pattern, but the data points elsewhere."
+- Cautionary: "The headline number hides an important caveat."
+- Teaching: "Follow this sequence to understand how the pattern emerges."
+- Action-oriented: "This evidence suggests where attention should go next."
+
+## Story Spine
+
+- Opening question
+- Context the audience needs
+- Main observation
+- Supporting evidence
+- Contrast or turning point
+- Caveat
+- Takeaway
+
+## Copy Elements
+
+- Title: clear, specific, and supported by data
+- Subtitle: adds context, timeframe, or caveat
+- Section headers: advance the story
+- Annotations: point to evidence, not decoration
+- Tooltips: explain values and definitions
+- Caveats: visible near the claim they qualify