Dashboard Build

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 if it is not already present at the root of the project.

Step 1: Build dashboard

1. You MUST ALWAYS copy the example app over, and modify it - this ensures less errors!
2. Investigate about the Vizro model by executing the schema fetching script. ALWAYS DO this for all models that you need - do NOT assume you know it. Execute the script like so: uv run ./scripts/get_model_json_schema.py <model_name> <model_name2> ... where <model_name> is the name of the model you want to get the schema for (prints the full JSON schema for each model to stdout). You can get an overview of what is available by calling the overview script like so: uv run ./scripts/get_overview_vizro_models.py (prints all available model names with one-line descriptions to stdout).
3. Build the dashboard config by changing the copied example app. Important: Very often normal plotly express charts will not suffice as they are too simple. In that case, refer to the custom charts guide to create more complex charts. These MUST be added to the correct section in the python app. Call the custom chart function from the Graph model in your dashboard app.
4. Run your dashboard app with uv run <your_dashboard_app>.py CRITICAL: After running this command, DO NOT run ANY other commands in that terminal. The dashboard takes time to start up (sometimes 10-30 seconds)
5. You MUST read the terminal to check for any errors, but do not put commands like sleep in it. Fix any warnings and even more important errors you encounter. ONLY once you see the dashboard running, inform the user. NEVER run any commands in that terminal after starting the dashboard.
6. When you iterate, no need to kill the dashboard, as we are using debug mode. Just save the file and it will reload automatically. Check the terminal occasionally for any failures. Once failed, you need to restart the dashboard.

Optimizations and common errors

• Colors: For Plotly charts and KPI cards, do not add colors in code — Vizro template defaults apply automatically. Only add chart colors if spec/3_visual_design.yaml defines color_decisions. For AG Grid cell styling (conditional formatting, heatmaps), use from vizro.themes import palettes, colors — never invent hex values. See selecting-vizro-charts skill.
• Data loading: For dashboards needing data refresh (databases, APIs) or performance optimization, see the data management guide for static vs dynamic data, caching, and best practices.
• KPI cards: Use built-in kpi_card / kpi_card_reference in Figure model only. Never rebuild as custom charts (exception: dynamic text). See selecting-vizro-charts skill.

REQUIRED OUTPUT: spec/4_implementation.yaml

Save this file BEFORE proceeding to Step 2:

# spec/4_implementation.yaml