Designing Vizro Dashboards

Structured requirements → layout → visualization workflow.

Workflow execution

Run Steps 1–3 in order; each step depends on the prior. Track progress:

Dashboard Development Progress:
- [ ] Step 1: Understand Requirements (define end user, dashboard goals, document decisions)
- [ ] Step 2: Design Layout & Interactions (wireframes, filter placement)
- [ ] Step 3: Select Visualizations (chart types, KPIs; colors only if user asked)

Interaction style: When gathering requirements or making design decisions, ask focused questions and present 2–5 numbered options so the user can choose quickly. Prefer using your client’s built-in multiple-choice or question UI to keep the interaction lightweight and clickable; if that isn’t available, use the same numbered format in plain text

Do not skip steps. Handle partial context as follows:

• User has data but no requirements → Start at Step 1
• User has requirements but no data → Ask for data or suggest sample data
• 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, ask for data or suggest sample data

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 are the end users of this dashboard? Per user type: What decisions do they need to make? What task/job do they need to accomplish?
2. Goals: What is the current problem to solve? What is the goal of this dashboard?
3. Data: What sources are available? What's the refresh frequency?
4. Structure: How many pages or views? What's the logical grouping?

Design Principles

• Limit KPIs: 5–9 primary metrics per page (7 ± 2 rule)
• 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/1informationarchitecture.md

Copy the template from [assets/1informationarchitecture.md](assets/1informationarchitecture.md) to spec/1informationarchitecture.md at the project root, fill in the placeholders, and save it BEFORE proceeding to Step 2.

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 [informationarchitecture.md](references/informationarchitecture.md); Anti-patterns: See [commonmistakes.md](references/commonmistakes.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

Load the designing-vizro-layouts skill for grid system, component sizing, filter placement, and selector rules. Use the [wireframe templates](references/wireframe_templates.md) when building ASCII wireframes for user approval.

Interaction Design

Beyond standard sidebar filters, Vizro supports advanced interactions where clicking a chart or table affects other components. Load the wiring-vizro-actions skill for the 6 named interaction patterns (Hierarchical Drill-Down, Single-Page Drill-Down, Comparison Spotlight, Multi-Dimensional Slice, Select & Explore, Data Export) with wireframes, spec entries, and code.

All advanced interactions follow Source → Control → Target: a source component (Graph or AgGrid — the components that carry click-data) sets an intermediate control (Filter or Parameter, always with an explicit id), which updates data-bearing target components (Graph, AgGrid, Figure, Table).

Decision flow — match data shape + user need to a pattern:

Hierarchy where detail needs its own page?    → Pattern 1 (Hierarchical Drill-Down)
Hierarchy where detail fits in a container?   → Pattern 2 (Single-Page Drill-Down)
Compare one entity vs many, keep context?     → Pattern 3 (Comparison Spotlight)
2+ categorical dimensions, click one cell?    → Pattern 4 (Multi-Dimensional Slice)
Users need to download data?                  → Pattern 5 (Data Export)
Otherwise → standard filters/parameters are sufficient

When NOT to use advanced interactions: view-only / executive dashboards, simple filtering needs (sidebar dropdown covers it), fewer than ~5 groups, or when you'd end up with more than 2 interaction patterns on a single page (becomes confusing).

For each interaction, document: source component, source value (column or "x"/"y"), control id + type (Filter/Parameter), targets, visibility (visible=False for highlight patterns), and whether it crosses pages (showinurl=True). See the wiring-vizro-actions skill for full templates.

REQUIRED OUTPUT: spec/2interactionux.md

Copy the template from [assets/2interactionux.md](assets/2interactionux.md) to spec/2interactionux.md at the project root, fill in the placeholders (including one ASCII wireframe per page), and save it BEFORE proceeding to Step 3. Delete the entire ## Interactions section if standard filters/parameters suffice.

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
• Each entry in interactions: maps to a named pattern from wiring-vizro-actions (or the absence of interactions is intentional)
• User has confirmed the interaction flow

Anti-patterns: See [commonmistakes.md](references/commonmistakes.md) section "Step 2: Layout & Interaction Mistakes"

Step 3: Select Visualizations

Goal: Choose appropriate chart types and establish visual consistency.

Chart Types, Colors & KPIs

Load the selecting-vizro-charts skill for chart selection, color strategy, anti-patterns, and KPI card rules. Key design decisions:

• Match chart type to data question (bar for comparison, line for trends, pie only for 2–5 slices)
• Colors: Do NOT include a ## Colors section in the spec. Vizro assigns palettes automatically. Only include if the user explicitly requested custom colors in their message.
• Use built-in kpicard / kpicard_reference; never rebuild as custom charts

REQUIRED OUTPUT: spec/3visualdesign.md

Copy the template from [assets/3visualdesign.md](assets/3visualdesign.md) to spec/3visualdesign.md at the project root, fill in the placeholders, and save it BEFORE proceeding to implementation (dashboard-build skill). Do not add a ## Colors section unless the user explicitly asked for custom colors — Vizro assigns palettes automatically.

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
• A ## Colors section is absent unless the user explicitly requested custom colors

Anti-patterns: See [commonmistakes.md](references/commonmistakes.md) section "Step 3: Visualization Mistakes"

Reference Files