dv-data-visualize

name	dv-data-visualize
description	Build and refresh visualization layers for Data Visualization Kit projects. Use when the task is dashboard construction, chart refresh, visualization-path selection, dashboard QA, or project-scoped visualization delivery that must follow the kit visualization workflow and resolve to one selected tool path.
license	MIT
argument-hint	[goal / task / brief]
metadata	{"author":"data-visualization-kit","version":"2.1.0"}

DV Data Visualize

Production-ready visualization delivery for Data Visualization Kit projects, with project-doc-driven routing, one-path dashboard ownership, validation after visual changes, and explicit handoff from prepared data into dashboard outcomes.

Workflow Obligation

This skill must follow ./.codex/workflows/data-visualize-workflow.md.

That means:

• read project docs before changing dashboards
• verify the prepared-data contract before visual work starts
• resolve exactly one visualization path for the active project
• build or refresh visuals on that path only
• validate the visualization pass after changes
• sync visualization notes and artifacts under the project docs tree

If this skill and the workflow file ever disagree, follow ./.codex/workflows/data-visualize-workflow.md.

When to Use

• building a new dashboard for an already prepared project
• refreshing charts, panels, filters, drill paths, or dashboard structure after source changes
• selecting or confirming the right visualization path for a project
• reconciling dashboard outputs with the prepared-data contract
• documenting visualization choices, scope changes, exports, screenshots, and validation status

Visualization Path Guide

Choose the selected path from project docs when it already exists.

Prefer Evidence.dev when:

• the deploy target is Netlify or Vercel
• the dataset is CSV, Excel, Parquet, or another static file format
• no live DB connection is required
• the portfolio piece should work without any server infrastructure

Prefer Metabase when:

• the project is general interactive BI
• stakeholders need accessible dashboard navigation and business-readable metrics
• the kit needs its default general BI path

Prefer Grafana when:

• the project is operational, observability-oriented, or time-series first
• the user workflow is monitoring, incident review, or telemetry-heavy analysis
• the dashboard depends on operational panels, variables, or alert context

Use Apache Superset only when:

• the project already selected Superset
• the estate is legacy and already depends on Superset datasets or dashboards
• migration analysis is explicitly part of the task

See: ./.codex/workflows/data-visualize-workflow.md

Visualization Mindset

The 10 Commandments of Visualization Delivery:

1. The prepared-data contract comes before dashboard polish
2. One selected tool path is better than a mixed dashboard stack
3. Dashboards are decision surfaces, not report dumps
4. Business meaning matters more than widget count
5. A broken metric is a data-contract issue until proven otherwise
6. Filters and navigation should match how users think
7. Validation is mandatory after visual changes
8. Project docs are part of the product, not afterthoughts
9. Path switches must be explicit
10. If the data is not trustworthy, route backward before decorating uncertainty

Data Visualization Foundation

Apply this foundation before choosing dashboard pages or chart types. It is distilled from the local data visualization ebook reference and should be treated as the default analytical lens for future visualization work.

Visualization Process

Every visualization pass should move through three checkpoints:

1. Filtering and processing

   • Refine, clean, compare, contextualize, and interpret the data before visual design starts.
   • If the dashboard needs guessed semantics, route backward to $dv-data-preparation.

2. Translation and visual representation

   • Convert the prepared data into a visual form by choosing the right chart, encoding, language, context, and tone for the audience.
   • Select visuals from the data relationship, not from chart preference.

3. Perception and interpretation

   • Make the visual useful by helping the viewer build knowledge, see patterns, and decide what to do next.
   • Add titles, labels, annotations, caveats, and next actions when the insight is not self-evident.

Classify the visualization intent before building:

Intent	Use when	Dashboard behavior
Explaining	A known question needs a clear answer	Lead with the answer, then evidence and next action
Exploring	The user needs to inspect the data and discover opportunities	Provide filters, drill paths, and multiple valid slices
Analyzing	The dashboard should reveal patterns, drivers, anomalies, or predictions	Support comparison, segmentation, variance, and interpretation

Data Types

Identify the field type before assigning it to a visual encoding:

Type	Subtype	Meaning	Typical use
Quantitative	Discrete	Countable numeric values	counts, units, number of customers, orders
Quantitative	Continuous	Numeric values on an interval	revenue, weight, height, duration, rate
Qualitative	Ordinal	Categories with meaningful order	month, rank, satisfaction level, lifecycle stage
Qualitative	Nominal	Categories without fixed order	product, market, channel, region

Data Relationships

For every visual, name the relationship it is meant to reveal:

Relationship	Question	Preferred visuals
Ranking	Which categories are highest or lowest?	sorted bar, column, leaderboard table
Deviation	How far is each value from average, target, or baseline?	deviation bar, line with reference line, waterfall
Correlation	Do two or more variables move together?	scatter plot, bubble chart, heat map
Distribution	How are values spread around a center or range?	histogram, box/violin if supported, density-style chart
Part-to-whole	What share does each part contribute to the total?	stacked bar, 100% stacked bar, donut for <=5 groups, treemap
Nominal comparison	How do unordered groups compare?	bar, grouped bar, table with conditional formatting
Series over time	How does a metric change over time?	line, area, column for discrete periods

Chart Selection Guide

Use this guide as the default chart choice matrix:

Chart	Best use	Avoid or caveat
Bar chart	Category comparison, ranking, nominal comparison	Sort by value unless chronology matters
Vertical column	Chronological or period-based comparison	Keep left-to-right time order
Horizontal bar	Long category labels or many categories	Use when labels need room
Stacked bar	Part-to-whole by category	Do not hide the main comparison
100% stacked bar	Share distribution when totals are not the point	Avoid if the viewer needs absolute volume
Histogram	Distribution of one numeric variable	Use bins that match the business meaning
Pie or donut	Simple part-to-whole with five or fewer groups	Avoid for precise comparison or many slices
Scatter plot	Relationship between two numeric variables	Add trend/correlation context when useful
Heat map	Matrix comparison, intensity, activity, or two-category intersection	Use accessible color scales and labels
Line chart	Trend, volatility, acceleration, deceleration over time	Avoid for unordered categories
Bubble chart	Three-dimensional comparison: x, y, size, optionally color	Watch overlap and size perception bias
Bubble map	Geographic value comparison with magnitude	Require clear location grain and legend
Radar chart	Cyclic or multi-axis profile comparison	Avoid for precise ranking across many entities
Waterfall chart	Cumulative positive and negative contributions	Use for bridge analysis, not generic trends
Treemap	Hierarchical part-to-whole and concentration	Avoid when exact small differences matter
Area chart	Volume over time or cumulative trend	Use line chart if volume/fill adds no meaning
Stacked area	Category contribution over time	Limit series count to keep shape readable
100% stacked area	Share mix over time	Avoid when total magnitude matters

Question-to-Chart Decision Framework

Start chart selection from the question the user needs answered:

Analytical need	Use when	Default visuals
Compare items	Compare values across categories	column, bar, clustered column/bar, trellis, radar for multivariate profiles
Time comparison	Compare changes over a period	line, multi-line, area, step chart, trellis line, week density
Static composition	Show part-to-whole at one point in time	stacked bar, percentage bar, pie/ring for simple shares, treemap
Non-static composition	Show part-to-whole over time	stacked area, 100% stacked area, waterfall for cumulative change
Correlation	Understand relationships between variables	scatter, bubble, heat grid, circle grid, event chart
Distribution	Understand frequency, spread, outliers, or clusters	histogram, box-and-whisker, scatter
Location	Show where things happen or do not happen	thematic/GIS map, bubble map, heat map, raster/custom map
KPI status	Show whether a metric is on target	big number, bullet/layered chart, meter/dial only when the metaphor adds clarity

Additional chart rules:

• Use trellis when one chart repeated by segment makes comparison easier than a crowded legend.
• Use clustered bar/column when comparing multiple category groups side by side.
• Use bullet/layered charts for compact actual-versus-target or spend-versus-budget views.
• Use step charts when the metric changes suddenly, timestamps are granular, or some dates are missing.
• Use week density for day-of-week and hour-of-day behavior such as usage, staffing, or resource planning.
• Use funnel charts only for ordered workflow stages where drop-off or bottleneck is the point.
• Use event charts when events need to be aligned with metric changes over time.
• Use heat grids for two dimensions plus one metric encoded by color.
• Use circle grids for two dimensions plus two metrics encoded by color and size.
• Use box-and-whisker when median, quartiles, spread, and outliers matter by category.
• Use thematic/GIS maps for regional boundaries, bubble maps for point magnitude, and raster/custom maps for non-geographic spatial layouts.
• Use big number only for a KPI that can stand alone with enough context, such as target, prior period, or threshold.

Formatting and Accessibility Rules

Format charts to reduce interpretation effort:

• Use color only when it carries meaning: category, ordered magnitude, status, threshold, or emphasis.
• Choose the color scale by data role:
  • Categorical: different colors for distinct categories.
  • Sequential: one ordered scale from low to high.
  • Diverging: two directions around a meaningful midpoint such as zero, target, or benchmark.
• Include a legend when color, size, or shape encodes multiple categories or metrics.
• Omit the legend when there is only one category and direct labels already explain the value.
• Prefer colorblind-aware palettes and do not rely on color alone; pair color with labels, position, shape, or text.
• Use grid lines to support threshold comparison, but keep them sparse enough that they do not dominate the data.
• Use labels when exact values matter, especially for static exports or charts without hover tooltips.
• Format axes with honest scales, readable intervals, clear units, and spacing that fits labels.

Clarity, Sorting, and Attention Rules

Make every visual tell the viewer what to see:

• Use query-style titles for neutral monitoring, such as Website traffic per quarter.
• Use insight-style titles for story dashboards, such as Website traffic is growing exponentially.
• Add chart descriptions when the data source, filter scope, calculation, or caveat is not obvious.
• Sort intentionally:
  • Alphabetical when users need to find a category quickly.
  • Ascending when progression or buildup is the story.
  • Descending when ranking or top/bottom comparison is the story.
  • Chronological when time order is the story.
• Add annotations or comments for outliers, context shifts, events, data quality caveats, and business interpretation.
• Direct attention with conditional formatting, reference lines, trend lines, forecasts, target bands, or thresholds.
• Highlight only the points that matter; too many highlights become noise.

Storytelling Dashboard Standard

Do not stop at "the visual uses the right fields." A portfolio-grade dashboard must guide the reader from evidence to interpretation to action.

Reference-Dashboard Storytelling Patterns

These are default dashboard design patterns learned from strong business storytelling dashboards. Apply them to future business and portfolio dashboard specs by default. The goal is not to copy visual decoration; the goal is to make every dashboard teach the reader what to see, why it matters, and what to do next.

Use these patterns by default for business dashboards:

1. Question headline

   • Page titles should read like a business question or decision area, not a generic noun.
   • Prefer: Which categories are driving revenue quality?
   • Avoid: Category Dashboard

2. Context-first KPI strip

   • Start each page with 3-5 KPI cards that establish scale and current status before charts.
   • KPI cards should include business labels, not technical measure names.
   • When possible, add comparison context: prior period, target, share, rate, rank, or variance.

3. One hero insight per page

   • Each page should have one primary chart that carries the main message.
   • Supporting charts should explain why, where, who, or what next.
   • If all charts have equal weight, the page is probably a chart collection instead of a story.

4. Chart title as interpretation

   • Visual titles should explain the analytical role.
   • Prefer: Discount pressure stays near 3% while revenue changes
   • Avoid: Revenue and Discount Impact by Month

5. Embedded insight callouts

   • Add a visible text box or annotation near the relevant chart with 2-4 bullets.
   • The text should state the conclusion in plain business language.
   • Do not force the viewer to infer the main point from lines and bars alone.

6. Metric definition beside ambiguous metrics

   • If a metric is not obvious, define it on the canvas or in a tooltip note.
   • Example: Discount Impact = GMV - Net Revenue; it estimates revenue reduced by discounts, not profit margin.

7. Cause-and-next-step flow

   • Arrange visuals so the reading path is natural:
     • What happened?
     • Where did it happen?
     • What drove it?
     • What should we inspect next?
   • End each page with a next action, drill path, or recommended segment.

8. Use comparison patterns, not isolated totals

   • Totals need context. Pair them with share, rate, variance, benchmark, ranking, or time comparison.
   • If two raw totals move together mechanically, replace one with a rate or contribution view.

9. Less is more

   • Prefer 3-5 purposeful elements per page.
   • Remove visuals that do not change the business interpretation.
   • Avoid repeating the same message in bar, donut, and table unless each view serves a different decision.

10. Explain visual roles in the build guide

    • For beginner-facing BI instructions, always say:
      • which visual to choose
      • which field goes into each field bucket
      • what the visual means
      • what a high or low value implies
      • what to click or filter next

Recommended page template:

Page title as business question

KPI strip:
- KPI 1: scale
- KPI 2: quality/rate
- KPI 3: driver/share
- KPI 4: behavior/efficiency

Hero visual:
- answers the page question directly
- includes benchmark, rate, or variance when useful

Support visual 1:
- explains driver, segment, or ranking

Support visual 2:
- explains mix, geography, cohort, or time pattern

Insight box:
- 3 short takeaways
- 1 "so what"
- 1 next action

For every dashboard page, define:

• Main question: the single business question this page answers
• KPI or threshold context: the numbers or reference points needed before reading charts
• Visual role: what each chart is supposed to prove, compare, rank, segment, or diagnose
• Insight text: 3-5 short bullets written on the dashboard that explain what the viewer should notice
• So what: why the pattern matters to the business
• Next action: what page, filter, segment, product, market, or cohort to inspect next

For every visual, document:

Requirement	Example prompt to answer
Question	What does this chart answer?
Data type	Which fields are quantitative discrete, quantitative continuous, ordinal, or nominal?
Relationship	Is this ranking, deviation, correlation, distribution, part-to-whole, nominal comparison, or time series?
Chart decision	Which analytical need does it serve: compare items, time comparison, composition, correlation, distribution, location, or KPI status?
Encoding	What goes in X-axis, Y-axis/Values, Legend, Size, Details, Tooltips, Rows, Columns?
Formatting	What color scale, legend, grid lines, labels, axis scale, and sorting are needed?
Interpretation	If the chart looks like this, what does it mean?
Caveat	What should the reader not over-interpret?
Action	What should the reader inspect next?

Prefer visuals that reveal a business pattern over visuals that merely restate totals. If two metrics move together because one is mechanically proportional to the other, use a rate, ratio, variance, contribution share, or benchmark instead of plotting both raw totals.

Examples:

• If Discount Impact moves like revenue, chart Discount Impact Rate to show whether discount pressure is actually changing.
• If a 100% stacked bar makes each category equal to 100%, use a donut, treemap, normal bar ranking, or contribution measure instead.
• If a bar chart ranks categories, label it as a driver/ranking chart and add a takeaway explaining which category to investigate.
• If a donut/treemap shows category mix, add a takeaway explaining whether revenue is concentrated or diversified.

Every main dashboard page should include a small narrative text box, similar to:

Key takeaways

- Revenue is large, but discount impact is material.
- Discount pressure is stable rather than accelerating.
- Revenue is diversified across categories; top categories are the first drill path.
- Next: inspect product-level drivers on the Product page.

Reference Navigation

Workflow Reference:

• ./.codex/workflows/data-visualize-workflow.md - required visualization workflow contract, routing, validation, docs sync

Visualization Domain Skills:

• evidence - static portfolio path for Evidence.dev
• metabase - default general BI path
• grafana - operational and time-series path
• apache-superset - legacy Superset path only

This skill is the project-scoped visualization domain guide for Data Visualization Kit. Use the downstream domain skills as selected paths, not as parallel active paths.

Operational Use

Use this skill for visualization domain judgment: path fit, chart choice, page storytelling, formatting, accessibility, and handoff expectations. Use ./.codex/workflows/data-visualize-workflow.md for the authoritative execution sequence and completion gates.

When building or reviewing a dashboard:

• apply the foundation sections above to pick charts and explain visual roles
• keep tool-specific implementation inside the selected downstream skill
• route backward to $dv-data-preparation when semantics or metrics are not trustworthy
• route forward to $dv-publish only after visualization state is stable and validated

Common Pitfalls to Avoid

1. Mixing multiple dashboard tools in one active visualization pass
2. Starting dashboard work before the prepared-data contract is actually trusted
3. Treating mismatched numbers as design issues instead of data-contract problems
4. Letting dashboard sprawl grow because no decision scope was enforced
5. Switching visualization path implicitly without recording it in project docs
6. Skipping validation after visual changes because the layout looks correct