Building Vizro Dashboards

A structured workflow for creating effective dashboards with Vizro.

How to Use This Skill

CRITICAL: Use this skill BEFORE implementation. After completing Steps 1-3, proceed to the dashboard-build skill for implementation and testing.

IMPORTANT: Follow steps sequentially. Each step builds on the previous.

Copy this checklist and track your progress:

Dashboard Development Progress:
- [ ] Step 1: Understand Requirements (discuss with user, document decisions)
- [ ] Step 2: Design Layout & Interactions (wireframes, filter placement)
- [ ] Step 3: Select Visualizations (chart types, colors, KPIs)
- [ ] Next: Use dashboard-build skill for implementation and testing

Do not skip steps. Handle partial context as follows:

• User has data but no requirements → Start at Step 1
• User has wireframes → Validate Step 1 decisions, then proceed from Step 2
• User has visual designs/mockups → Validate Steps 1-2 decisions, then proceed from Step 3
• User asks to "just build it" → Explain value of steps, offer to streamline but not skip

For simple dashboards (single page, less than 5 charts): Steps 1-3 can be abbreviated but not skipped entirely.

Spec Files: Documenting Decisions

IMPORTANT: Each step produces a spec file in the spec/ directory to document reasoning, enable collaboration, and allow resumption in future sessions. Create the spec/ directory at project start.

Step 1: Understand Requirements

Goal: Define WHAT information is presented and WHY it matters.

Key Questions to Discuss

1. Users: Who uses this dashboard? What decisions do they make?
2. Questions: What are the 3-5 most important questions this answers?
3. Data: What sources are available? What's the refresh frequency?
4. Structure: How many pages? What's the logical grouping?

Design Principles

• Limit KPIs: 5-7 primary metrics per page maximum
• Clear hierarchy: Overview → Detail → Granular (max 3 levels)
• Persona-based: Different users may need different views
• Decision-focused: Every metric should inform a decision

REQUIRED OUTPUT: spec/1_information_architecture.yaml

Save this file BEFORE proceeding to Step 2:

# spec/1_information_architecture.yaml
dashboard:
  name: [Name]
  purpose: [One sentence goal]
pages:
  - name: [Page Name]
    purpose: [What question does this answer?]
    kpis: [List of 3-7 key metrics]
data_sources:
  - name: [Source Name]
    type: [csv/database/api]
decisions:
  - decision: [What was decided]
    reasoning: [Why this choice was made]

Validation Checklist

Before proceeding to Step 2:

• Every page has a clear, distinct purpose
• KPIs are measurable and actionable
• Data sources are accessible
• User has confirmed the structure

Detailed guidance: See information_architecture.md; Anti-patterns: See common_mistakes.md section "Step 1: Requirements Mistakes"

Step 2: Design Layout & Interactions

Goal: Define HOW users navigate and explore data.

Vizro Navigation Architecture

Tier 1: Global Navigation
├── Multi-page sidebar (automatic in Vizro)
└── Page selection

Tier 2: Page-level Controls
└── Filters/Parameters in left collapsible sidebar

Tier 3: Component-level
├── Container-specific filters/parameters
├── Cross-filter, cross-highlight interactions
└── Export actions

Layout Strategy

Optimal Grid Configuration:

• Always use row_min_height="140px" (at page or container level)
• 12 columns recommended (not enforced) - flexible due to many divisors (1, 2, 3, 4, 6, 12)
• Control height by giving components more rows

Component Sizing (based on 12-column grid, height = rows × 140px):

Exceptions - size based on content to render:

• Text-heavy Card → treat like a chart (3+ rows)
• Small Table (less than columns) → doesn't need full width
• Button → 1 row is enough

Layout Rules:

• Place 2-3 charts per row (side-by-side)
• Full-width ONLY for time-series line charts
• Give charts minimum 3 rows (use *[[...]] * 3 pattern)
• Use -1 for intentional empty cells

Filter Placement & Selectors

Filter needed across multiple visualizations?
├─ YES → Page-level (left sidebar)
└─ NO → Container-level (top of the container)

Choose appropriate selectors - don't default to Dropdown:

REQUIRED OUTPUT: spec/2_interaction_ux.yaml

Save this file BEFORE proceeding to Step 3:

# spec/2_interaction_ux.yaml
pages:
  - name: [Must match Step 1]
    layout_type: grid  # or flex
    grid_columns: 12
    grid_pattern: [[0, 0, 0, 1, 1, 1, 2, 2, 2, 3, 3, 3]] # Component placement

    containers:
      - name: [Container Name]
        has_own_filters: true/false
    filter_placement:
      page_level: [columns with selector types]
      container_level: [columns with selector types]
wireframe: |
  [ASCII wireframe for ALL pages]
decisions:
  - decision: [What was decided]
    reasoning: [Why this choice was made]

Validation Checklist

Before proceeding to Step 3:

• Layout follows Vizro constraints
• Filter placement is intentional and documented
• User has been presented ASCII wireframes for every page and approved them

Wireframes & examples: See layout_patterns.md; Anti-patterns: See common_mistakes.md section "Step 2: Layout Mistakes"

Step 3: Select Visualizations

Goal: Choose appropriate chart types and establish visual consistency.

Chart Type Quick Reference

Chart Anti-Patterns (Never Use)

• 3D charts, Pie charts with 6+ slices, Dual Y-axis, Bar charts not starting at zero

Color Strategy

Primary Rule: Let Vizro handle colors automatically for standard charts.

When to specify colors:

• Semantic meaning (green=good, red=bad)
• Consistent entity coloring across charts
• Brand requirements

Vizro Semantic Colors:

success_color = "#689f38"  # Green - positive
warning_color = "#ff9222"  # Orange - caution
error_color = "#ff5267"  # Pink/red - negative
neutral_color = "gray"  # Inactive

KPI Card Pattern

Use kpi_card() for simple metrics, kpi_card_reference() for comparisons. Use reverse_color=True when lower is better (costs, errors). NEVER put kpi_card or kpi_card_reference as a custom chart or re-build KPI cards as custom charts, use the built-in kpi_card and kpi_card_reference in Figure model instead. Only accept exceptions for when the KPI card is strictly not possible, for example when dynamically showing text as a KPI card.

Chart Title Pattern

IMPORTANT: Titles go in vm.Graph(title=...), NOT in plotly code.

REQUIRED OUTPUT: spec/3_visual_design.yaml

Save this file BEFORE proceeding to implementation (dashboard-build skill):

# spec/3_visual_design.yaml
visualizations:
  - name: [Chart Name]
    type: [bar/line/scatter/etc]
    needs_custom_implementation: true/false
    reason: [if custom: has_reference_line/needs_data_processing/etc]

color_decisions:
  - component: [Name]
    reason: [Why non-default color]
    colors: [List of hex codes]

kpi_cards:
  - name: [KPI Name]
    value_column: [column]
    format: [e.g., '${value:,.0f}']
    has_reference: true/false

decisions:
  - decision: [What was decided]
    reasoning: [Why this choice was made]

Validation Checklist

Before proceeding to implementation (dashboard-build skill):

• Chart types match data types (no pie charts for time series)
• No anti-patterns used
• Custom chart needs are identified
• Color usage is consistent and intentional

Chart decision trees: See chart_selection.md; Anti-patterns: See common_mistakes.md section "Step 3: Visualization Mistakes"

Reference Files

Quick Reference: Vizro Components

Components: Dashboard, Page, Container, Tabs, Graph, Figure, AgGrid, Card, Filter, Parameter, Selector, Button

Key Imports: import vizro.models as vm, from vizro import Vizro, import vizro.plotly.express as px, from vizro.tables import dash_ag_grid, from vizro.figures import kpi_card, kpi_card_reference, from vizro.models.types import capture