Agent-Skills.md

Agent Skills: Vizro Chart Best Practices

Use this skill when choosing chart types, applying Plotly Express conventions, configuring colors, or building KPI cards for Vizro dashboards. Activate when the user asks which chart fits their data, needs custom chart functions, wants to set colors or palettes, or is creating KPI metric cards.

UncategorizedID: mckinsey/vizro/selecting-vizro-charts

Repository

mckinsey/vizro
mckinseyLicense: Apache-2.0
3,658259

Install this agent skill to your local

pnpm dlx add-skill https://github.com/mckinsey/vizro/tree/HEAD/vizro-e2e-flow/skills/selecting-vizro-charts

Skill Files

Browse the full folder contents for selecting-vizro-charts.

Download Skill

Loading file tree…

vizro-e2e-flow/skills/selecting-vizro-charts/SKILL.md

Skill Metadata

Name
selecting-vizro-charts
Description
Use this skill when choosing chart types, applying Plotly Express conventions, configuring colors, building KPI cards, or adding tables (AG Grid) to Vizro dashboards. Activate when the user asks which chart fits their data, needs custom chart functions, wants to set colors or palettes, is creating KPI metric cards, or needs a tabular detail view.

Vizro Chart Best Practices

Chart Selection

| Data question | Chart | | ----------------------- | --------------------------- | | Compare categories | Bar (horizontal preferred) | | Trend over time | Line (12+ points) | | Part-to-whole (simple) | Pie/donut (2–5 slices only) | | Part-to-whole (complex) | Stacked bar | | Distribution | Histogram or box | | Correlation | Scatter |

Never use: 3D charts, pie with 6+ slices, dual Y-axis, bar charts not starting at zero.

Plotly Conventions

  • Plotly Express does not aggregate. Pre-aggregate in app.py or custom chart functions.
  • Bar: sort by value (largest→smallest) unless time-based; always start at zero.
  • Line: pre-aggregate and sort by x ascending.
  • Remove axis title when ticks are self-explanatory. Remove legend title (keep items only).

Color Rules

  • Plotly charts & KPI cards: Do not specify colors — no marker_color, hex codes, color_discrete_map, or color_discrete_sequence. This applies even for categories with apparent semantic meaning. Only override when the user explicitly asks.
  • AG Grid: Does not pick up Vizro template colors automatically. Use from vizro.themes import palettes, colors for cell styling.
  • See chart-best-practices.md for palette names and import patterns.

Custom Charts (@capture("graph"))

Use when: aggregation/sorting needed, update_layout()/update_traces() calls, reference lines, parameter-driven logic, dual-axis, multi-trace go.Figure(), shared legend control.

In practice, most bar and line charts need @capture("graph") functions that aggregate data inside. Inline px.bar(data_frame="raw", x="region", y="revenue") on detail-level data stacks individual rows as separate rectangles instead of summing — producing visually broken charts.

KPI Cards

  • Use built-in kpi_card / kpi_card_reference from vizro.figures in Figure model.
  • Never rebuild KPI cards as custom charts. Exception: strictly impossible with built-in (e.g. dynamic text).
  • Titles go in figure args (_target_: kpi_card → title:), not on the component.

Tables

  • Use vm.AgGrid with figure=dash_ag_grid(data_frame=...) from vizro.tables. AG Grid is the only table component you should write.
  • Never use vm.Table / Dash DataTable. Never fake a table with Plotly (heatmap-with-text, px.imshow annotated as a table, scatter-with-text). Even small tables go in AG Grid; KPI cards or a horizontal bar chart are the only acceptable lighter alternatives.
  • For custom column logic, write @capture("ag_grid") with data_frame as the exact DataFrame argument name (not df, not data).
  • See the dashboard-build skill's example_ag_grid.py for the two canonical patterns (drop-in factory + @capture("ag_grid") for runtime-parameterized grids) and the Dash AG Grid / JS AG Grid knowledge-mapping notes.

Deep Dive

Load chart-best-practices.md when you need: extended chart type decision tree, Plotly Express formatting conventions (100% stacked bar, axis/legend cleanup), palette/color names and use cases, accessibility rules, or detailed @capture("graph") guidance.