visualize-data

name	visualize-data
description	Design, build, revise, or QA quantitative charts and figures. Use when an analytical answer needs visual judgment, whether for an inline answer, report, dashboard, notebook, or artifact.

Related Skills

Use $metric-diagnostics when the visual needs an explanation of a metric movement.

Use $build-report when the visual is part of a durable analytical report.

Data Visualization

Create quantitative visuals that are analytically sound, immediately readable, and polished enough to ship in a report, memo, slide, dashboard, notebook, widget, or HTML artifact. Treat charts as evidence for a takeaway. Redesign charts that are visually attractive but analytically weak, and revise charts that are technically correct but hard to interpret.

Runtime Delivery Routing

If surface = chatgpt_web and mode = work_mode are both positively identified, do not render with Data Analytics MCP chart or table widgets, do not call render_chart or render_table for inline delivery, and do not select an MCP artifact as the visual surface. This branch applies only after another workflow has already selected inline delivery; it does not choose inline over a report, dashboard, HTML, notebook, or other surface. For an already-selected inline visual, prefer native Work Mode rendering and read native-inline-visualizations.md to choose and invoke charts_widget_v2 or app_block. For one supported bar, line, pie, or scatter chart, treat charts_widget_v2 as directly surfaced in this runtime and emit its live genui content reference before considering fallback; do not self-declare it unavailable or search for it. The complete outer shape is genui{"charts_widget_v2":{"content":{...}}}: replace {...} with the real chart spec and emit the reference without Markdown backticks. The inner chart spec alone is not a response; do not print bare JSON, plain HTML, or a code fence. Keep app_block conditional on the host surfacing it. If the Visualize plugin is installed, also consult and follow its current visualization guidance for native chart or app-block authoring, while keeping this skill's delivery gate and fallback order authoritative. If an emitted native visual is rejected or fails to render, use a reproducible static/Matplotlib chart that fits a non-MCP surface; use a compact table only if no visual renderer can be delivered. Use static or Matplotlib charting for this native-render failure fallback or when the user explicitly asks for Python, a static image/file, notebook-oriented output, or export. A successful Data Analytics MCP tool result is not delivery confirmation in web Work Mode, so do not say a visual was plotted or rendered above unless the selected native or non-MCP surface actually rendered. MCP servers and other callable tools remain valid data sources.

Whenever the selected report or dashboard delivery surface is HTML, read recharts-html.md and use its packaged Recharts-in-HTML path with same-data static fallbacks. This includes Codex explicit HTML, ChatGPT web Work Mode, and HTML used for PDF, Google Docs, or Google Slides conversion.

Outside positively identified web Work Mode, keep the existing surface selection rules unchanged.

Chart Selection

Common surface forms should be named in the chart contract when the final surface is a report, dashboard, slide, notebook, widget, or HTML artifact.

Data relationship	Best chart	Use it well
Trend over time or ordered axis	line	Show enough points to reveal shape; use area only when filled magnitude helps, and sparkline only in dense KPI cards
Composition over time	stackedArea	Use when parts should read as one total; switch to line when comparing component trajectories matters more
Comparison across categories	bar	Sort when order is not semantic; use horizontal bars for long labels; avoid redundant legends
Ranking or top-N	leaderboard	Keep it compact and single-measure; switch to ranked bar when comparison needs more chart context
Part-to-whole composition	stacked bar	Keep the denominator explicit; use pie only for a rough read with few slices
Distribution or spread	histogram	Use numeric bins that reveal shape; switch to boxPlot when comparing groups is the point
Distribution across groups	boxPlot	Use when median and spread matter more than full shape; switch to histogram when shape needs space
Relationship between two numeric variables	scatter	Use numeric x and y at a meaningful observation grain with enough distinct points to show a pattern; retain point labels, sample/volume fields, and one useful grouping candidate when safe
Dense two-dimensional pattern or cohort matrix	heatmap	Use for matrix shape or intensity; switch to scatter when point-level variation matters
Additive bridge from start to end	waterfall	Use only when drivers sum cleanly to the end value; otherwise use ranked bar
Ordered stage progression or drop-off	funnel	Use only for ordered single-series stages; prefer stage bar when funnel geometry distorts comparison

Workflow

1. Define the analytical question and one-sentence takeaway before choosing a chart. Identify the final surface, the intended comparison, and the context needed to make the visual honest.
2. Choose the simplest defensible family and variant from Chart Selection. Coordinate with $build-dashboard or $build-report when the visual belongs to those artifacts, and use $validate-data when the supporting analysis needs validation.
3. Write a compact chart contract before plot code, dashboard configuration, or renderer-specific implementation work. Include:
   • analytical question and takeaway
   • canonical family and concrete variant
   • data sufficiency for the chosen visual: expected row count, temporal point count for trend views, scatter observation count and grain, requested date range and grain, and fallback if the first query is too sparse
   • surface-native chart type, Recharts HTML chart type, or explicit static renderer when a concrete renderer has been selected
   • delivery-specific constraints only after the delivery surface is chosen; for MCP widgets or app artifacts, use the shared MCP specification
   • palette policy, approved palette roots, and non-color distinction plan
   • output footprint, final container, export paths or delivery target, and the final QA surface
4. Select the delivery path that matches the final surface.
   • In positively identified web Work Mode, only after the active workflow has already selected inline or chat-visible delivery, read references/native-inline-visualizations.md and prefer native Work Mode rendering; do not call render_chart or render_table for inline delivery. For one supported bar, line, pie, or scatter chart, emit the directly surfaced charts_widget_v2 live content reference before fallback. Use a reproducible static/Matplotlib chart only after that emitted reference is rejected or fails to render, or when no suitable native renderer exists for the requested chart family; use a compact table only if no visual renderer can be delivered, and do not describe a Data Analytics MCP tool result as rendered above. Use static or Matplotlib charting for this native-render failure fallback or for an explicit Python, static image/file, notebook, or export request.
   • Outside web Work Mode, default to Data Analytics MCP chart widgets for ad hoc, inline, chat-visible, or otherwise unspecified chart requests. Treat "make/show/render this chart" as an MCP widget request unless the user explicitly asks for Python, a static image/file, notebook code, HTML, BI/dashboard editing, slides/docs export, or no rendered artifact.

• Use governed BI or dashboard-native widgets when that surface owns rendering; this skill should supply the visual spec and QA bar.
• Implement local HTML/CSS/SVG/canvas/JavaScript visuals only when the final surface truly requires local rendering, custom interaction, offline portability, or a larger artifact than a widget can carry.

5. Build in this order: format, structure, color, then QA. Choose the family, variant, and delivery surface first; decide labels, annotations, benchmarks, and retained information second; choose palette policy and explicit colors last.
6. Render or export the chart in its real context. For HTML reports and dashboards, inspect both the live Recharts mount and its same-data static fallback. For explicit standalone static output, save and inspect the image format the user requested.
7. Inspect the visual in the final report, slide, dashboard, notebook, widget, or HTML layout. Revise before delivery when the chart, labels, color system, or container fails final-context QA.
8. For shipped reports or dashboards with multiple visuals, maintain a compact chart map in notes or source material. Name the section, analytical question, selected family and chart type, fields, supported takeaway, palette policy, and delivery artifact, image path, or provenance source.

Standards

Selection Rules

Start from the analytical question and comparison the reader needs to make, not from a favorite chart type. Keep the top-level set small:

• Tables & Scorecards
• Trend
• Comparison & Ranking
• Composition
• Distribution
• Relationship
• Uncertainty & Benchmark
• Matrix & Cohort
• Decomposition & Progression

Concrete forms such as highlighted multi-series line, Likert, pie, Pareto, waterfall, faceted dot & interval, and cohort heatmap are variants inside these families, not peer families.

• Use charts for shape and comparison; use tables for exact lookup. If a table would show 3-8 comparable entities with one dominant numeric measure, prefer a bar, dot, lollipop, leaderboard, or other chart unless exact row lookup is the point.
• When reviewed evidence contains many comparable values, rows, categories, segments, or time points, default to rendering a simple chart on the selected delivery surface when that surface is available and safe. Skip rendering only when exact row lookup is the main task, the data is too sparse for an honest chart, the user asked for table/prose only, or the selected surface cannot support a useful visual.
• Do not choose line merely because the prompt says "trend" or "trending". Decide first whether the reader needs current status, movement, variance to plan, mix, concentration, drivers, progression, or distribution.
• Do not ship underpowered trend charts. For line, area, sparkline, indexed-trend, or other time-series views, first try to expose either a finer time grain or a longer date range so the displayed series has enough observed points to show shape. As a default, aim for at least 8-12 temporal points for a trend visual; if the available evidence has only a few anchor periods, query daily or weekly rows, extend the lookback, or add a meaningful segment/comparator before rendering. Use a KPI strip, grouped bar, slope chart, table, or narrative callout instead when the question is really a small set of discrete period comparisons.
• Do not ship underpowered scatter charts. A useful scatter needs enough comparable observations to reveal shape, clustering, outliers, or exceptions; as a default, aim for at least 12-20 meaningful points and treat fewer than 8 points as a likely table, bar, dot/lollipop, or narrative comparison unless each point is intentionally important and labeled. If the first result only has a few segment aggregates, make one targeted attempt to query a finer analytical grain such as account, workspace, user cohort, customer, model, endpoint, route, geography, or segment-by-period. Keep all plotted rows at the same grain, and do not mix totals, averages, and detail rows in one scatter.
• For scatter charts, choose x and y measures that can plausibly vary independently and share the same denominator, time window, population, and filters. Include the denominator, sample size, or volume metric used to judge reliability, and use a size encoding only when that third metric materially changes interpretation. Add a point-label field for small or executive-facing scatters, and retain a meaningful categorical field such as segment, plan, route, product line, model family, or region for optional color or filtering. Avoid coloring by a unique row id; use labels or the table for exact identity instead.
• Use horizontal bars for long labels and sorted bars when order has no semantic meaning.
• Use compact leaderboard-style ranked bars only for top-N previews with one numeric value and 3-8 visible rows. Default to 5-6 rows in compact dashboard cards. Use a paginated table for long-tail browsing or exact lookup, Pareto for cumulative concentration, and waterfall for additive start-to-end driver bridges.

Surface And Implementation

• For data visualization requests outside web Work Mode where the user has not chosen a file, notebook, BI/dashboard, report, slide, docs, HTML, or no-render output surface, render with Data Analytics MCP chart widgets by default when the MCP widget tools are available. In web Work Mode, only after inline delivery has already been selected, read references/native-inline-visualizations.md and prefer native Work Mode rendering; for one supported bar, line, pie, or scatter chart, emit the directly surfaced charts_widget_v2 live content reference before fallback. Use a reproducible static/Matplotlib chart before a compact table fallback only after that emitted reference is rejected or fails to render, or when no suitable native renderer exists for the requested chart family. Do not call render_chart or render_table for web Work Mode delivery, do not treat an ok:true Data Analytics MCP tool result as proof that the browser rendered the visual, and use static or Matplotlib charting only for that native-render failure fallback or when the user explicitly asks for Python, a static image/file, notebook-oriented output, or export. When the user explicitly chooses another surface, keep this skill's output to chart selection, data planning, implementation guidance, and QA for that surface.
• When the selected delivery surface is an MCP Apps widget or Data Analytics MCP report/dashboard artifact, read ../../src/analytics-app-core.md after selecting the chart family. Do not let an MCP-supported type list drive general chart selection for non-MCP surfaces.
• When rendering an MCP inline chart from reviewed query results, call render_chart with source metadata, an exploration-ready table, chart encodings, and display settings. Do not create an intermediate Python chart image for the same result unless the user explicitly asked for Python/static output or the widget renderer is unavailable.
• Any table that powers a chart must be richer than the minimum fields needed to draw that chart. Do not ship source-data tables containing only x, y, and optional series/color fields when the reviewed result can safely include contextual dimensions, numerator/denominator fields, date or cohort fields, ranks, benchmarks, comparison-period values, or adjacent measures. If privacy, query cost, source limits, or metric definitions prevent a richer table, state that limitation in the chart/report notes.
• Before rendering or exporting, inspect the reviewed result table for information density. If the chart would render fewer than 8 temporal points, fewer than 4 meaningful categories, fewer than 8 scatter observations, or a nearly straight two/three-point path, make one targeted attempt to improve the supporting data by querying a finer grain, extending the time range, or adding a relevant breakdown that supports the same claim. If that is blocked by source limits, query cost, privacy, or metric definition, record the limitation and switch to a more honest form such as KPI cards, grouped bars for discrete periods, a table, or prose with exact values.

Visual Design

• Match chart titles to the surface. Report and dashboard visual headers should stay neutral and descriptive, with takeaways in adjacent narrative text. Standalone static charts may use takeaway-led titles when there is no surrounding narrative block.
• Put metric details, units, denominator, date range, cohort, filters, sample size, or volume in the subtitle when needed. Notes can add caveats, but do not replace the subtitle.
• Use a single font family across charts and surrounding output when possible. Prefer white or near-white backgrounds, quiet grey grid lines, deep charcoal text, and restrained approved palette roots centered on blue, gold, orange, olive, and pink.
• Do not rely on color alone. Use tone, open fill, marker fill, line style, direct labels, ordering, or faceting when series or states need separation.
• Only set color or series encodings for meaningful grouping dimensions such as segment, product_line, or series when they are not already the sole axis category. Omit color for single-series charts and do not manufacture or duplicate a grouping field just to produce a legend.
• Choose one palette policy before plotting:
  • single-root preferred: one non-neutral root plus shades, open fills, and neutral references for simple trends, ranks, distributions, relationships, matrices, and repeated panels.
  • hard two-root cap: at most two non-neutral roots plus neutrals for binary, signed, focal-vs-context, benchmark, comparator, waterfall, Pareto, diverging, highlighted trend, and ordered line-dot charts.
  • relaxed multi-category: up to five approved roots when category identity is the point, such as pie, stacked bars, stacked area, grouped bars, and stage bars. If more are needed, group to top-N plus Other or change forms.
• Use each selected root's base tone as the default non-neutral mark color. Reserve mid for deliberate higher-contrast exceptions, use dark for keylines, outlines, labels, or reference strokes, and use light, xlight, or open for supporting fills.
• Generate explicit palette maps from declared colors. Do not let plotting library categorical defaults choose shipped chart colors.
• For signed values, avoid green/red by default. Use dark versus open/light fills, direct signed labels, and clear zero-line context unless documented domain semantics require an exception.
• For waterfall charts, use matched neutral start and end anchors plus exactly two non-neutral delta colors: one positive and one negative. Do not introduce extra hues or darker/lighter non-neutral keylines for individual drivers.

Quality Bar

• Chart choice should follow Chart Selection.
• Choose and honor an explicit delivery surface. Use MCP widgets only when that surface is available, safe, useful, and not contrary to the user's requested output mode.
• Keep chart contracts, omitted-chart explanations, validator notes, and QA rationale out of visible executive report bodies unless the user asks for methodology or the detail changes the reader-facing takeaway.
• Explicit standalone static/Python plotting code should be reproducible and visibly adapted to the requested chart contract. Generic ad hoc snippets are acceptable only for exploratory charts.
• The form must match the analytical comparison, and scales must stay honest and consistent across comparable charts.
• Standard bar charts that compare absolute magnitude should start at zero. Delta-focused waterfalls, bridges, variance bars, and small-multiple movement charts may use non-zero or narrowed domains only when the zero baseline would materially hide the intended change and the chart carries exact labels plus a clear scale cue.
• Data grain, filters, date range, denominator, and units must match the claim the chart supports.
• Every shipped chart must have a visible title appropriate to its surface and a subtitle that carries needed units, time/cohort context, denominator, sample size, or volume.
• Labels, ticks, titles, legends, callouts, benchmark labels, and annotations must not collide, clip, or detach from the evidence in the exported chart or final container.
• Long labels, negative values, outside-end labels, zero-line context, and direct value labels need explicit layout space.
• Multi-series filled marks need distinct tones, open fills, keylines, marker fills, line styles, direct labels, or faceting. Visually identical adjacent or overlapping fills fail QA.
• Line styles, marker fills, open fills, keylines, ordering, faceting, and direct labels should remain legible in grayscale when they carry distinction.
• Positive and negative states should use tone, open fill, zero-line context, and signed labels rather than default green/red semantics unless the exception is documented.
• Exported SVG or HTML colors should match declared palette roots plus neutrals; remove unused multi-hue tokens unless documenting an intentional exception.
• Chart scaffolding should stay quiet: no arbitrary colored backgrounds, gradients, decorative guides, inconsistent stroke widths, or decorative mark fills. Filled marks should keep keylines, and benchmark, calibration, and reference lines should use dark-neutral styling.
• Titles, legends, and primary labels should use dark ink and share a clear header anchor. Numeric ticks and direct value labels should use mono styling where the template system calls for it.
• Research charts should use the locked top-right blossom placement; third-party, partnership, and non-research charts should omit it.