Designing Vizro Layouts
Designdesigning-vizro-layoutsDesigning Vizro Layouts is an Agent Skill for design published in the mckinsey/vizro repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use this skill when designing or building Vizro dashboard layouts — grid configuration, component sizing, filter/parameter placement, selector types, or container patterns. Activate when the user is creating wireframes, defining page structure, placing controls, or sizing charts.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/mckinsey/vizro/blob/HEAD/vizro-e2e-flow/skills/designing-vizro-layouts/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/designing-vizro-layouts, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Vizro Layout Guidelines
Core Rules
- Use
type: grid(notvm.Layout). Recommended: 12 columns,row_min_height: "140px". - Use
-1for empty cells. Every component must form a perfect rectangle in the grid. - Place 2–3 charts per row. Full-width only for time-series line charts.
- Modifying existing layouts: Replicate the original structure and apply only the technical constraints below. See layout-guidelines.md for details.
Component Sizing (12-col grid, 140px rows)
| Component | Columns | Rows | Height |
|---|---|---|---|
| KPI Card | 2–3 | 1 | 140px |
| Small Chart | 4 | 3 | 420px |
| Large Chart | 6 | 4–5 | 560–700px |
| Table | 12 | 4–6 | 560–840px |
KPI cards: Place in the page Grid with equal columns and equal rows per card (e.g. 4 cards = 3 cols each). Use -1 for remaining empty cells. See layout-guidelines.md for the full KPI count lookup table and YAML examples. Charts need at least 2–3 rows to avoid looking squeezed.
Filter Placement
- Page-level (left sidebar): filters shared across multiple components
- Container-level (above container): filters scoped only to the components inside that container
- Prefer Filters over Parameters. Do not set
targets:by default — all components containing the specified column are automatically affected. Only settargets:when you want to limit which components are affected.
Selectors
Default: Just provide the column name to Filter or Parameter — Vizro auto-selects the appropriate selector based on the data type. Only override when the auto-selected selector doesn't fit:
| Data type | Selector | Example |
|---|---|---|
| 2–4 options | RadioItems | Region (N/S/E/W) |
| 5+ options | Dropdown | Category (many) |
| Numeric range | RangeSlider | Price ($0–$1000) |
| Single number | Slider | Year (2020–2025) |
| Date | DatePicker | Order date |
| Multi-select | Checklist | Status (Active, etc.) |
Deep Dive
Load layout-guidelines.md when you need: grid YAML examples (correct vs incorrect), flexible width distributions, container patterns (plain/filled/outlined), visual hierarchy principles, or Vizro platform constraints.