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:

Data Types

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

Data Relationships

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

Chart Selection Guide

Use this guide as the default chart choice matrix:

Question-to-Chart Decision Framework

Start chart selection from the question the user needs answered:

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:

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