dashboard-beautify

name	dashboard-beautify
description	Design and build production-grade dashboards and infographics with Dash and Plotly Python: layout strategy, colour semantics, accessibility, and pre-ship validation. Use when creating or beautifying a dashboard, KPI panel, or data infographic.
metadata	{"skill-author":"Marie-Lynne Block","version":"0.0.4"}

Data Atelier

Production-grade dashboards and infographics with Dash and Plotly Python.

Philosophy: form follows function, colour communicates, every design decision earns its place. A dashboard is a curated argument made from data — not a chart dump.

Default target: production delivery. Optimise for correctness, maintainability, and accessibility from the start — not as an afterthought.

---

Before writing any code — establish the brief

1. What is the primary question this dashboard answers? The answer must be visible in < 3 seconds.
2. Who is the audience? Executive / analyst / operational — determines density, annotation level, interactivity depth.
3. Single infographic or multi-panel dashboard? Different layout and scope strategies apply.
4. What is the data shape? Time series / categories / relationships / distributions / compositions.
5. What is the data source and refresh cadence? Determines caching strategy and performance approach.

If any of these are unanswered, ask before writing code.

---

Step 1 — Data quality gate

Run this before any design work. A beautiful dashboard built on bad data is worse than no dashboard.

Read references/data-quality.md for full checks. Minimum required:

• Missingness: identify null rates per column — flag anything > 5% to the user before proceeding
• Duplicates: check for duplicate rows on the natural key; deduplicate or explain why not
• Outliers: surface extreme values — confirm they are real, not ingestion errors
• Unit consistency: confirm all numeric columns use consistent units (£ vs $, thousands vs millions)
• Metric definitions: confirm calculated fields (rates, ratios, aggregations) match the agreed definition
• Timezone normalisation: all timestamps must be in a single consistent timezone before display

---

Step 2 — Choose the right chart

Data intent	Recommended	Never
Change over time	Line, area, connected scatter	Bar (unless discrete periods only)
Compare categories	Horizontal bar (many labels), column (few)	Line (implies continuity between categories)
Part of a whole	Stacked bar, treemap, sunburst	Pie with > 4 slices
Distribution	Histogram, violin, box plot	Bar chart of means (hides spread)
Correlation / relationship	Scatter, bubble (3rd variable as size)	Line
Flow / transfer	Sankey	—
Multi-variable dense	Heatmap, parallel coordinates	Radar/spider (angle distorts magnitude)
Single KPI	Styled html.Div card — no chart	Any chart type
Multiple series, different scales	Small multiples (facets)	Dual-axis (almost always misleading)

Hard anti-patterns — flag to user unless explicitly overridden:

• 3D charts (perspective distortion destroys accuracy)
• Rainbow / Jet colormaps on continuous data (use Viridis, Cividis, Magma)
• Pie charts with > 4 slices
• Dual-axis charts

Read references/chart-selection.md for edge cases and the full decision framework.

---

Step 3 — Colour strategy

Read references/colour-theory.md for the full palette library and per-theme Plotly template code.

This skill is theme-agnostic. Select the appropriate theme for the project and apply it consistently — do not mix themes within a project. Available themes documented in the reference:

• Nord — soft, cool-toned, professional; well-suited to extended use and healthcare/public sector
• Okabe-Ito — colourblind-safe, vivid; good default when no brand constraint applies
• Muted Professional — desaturated enterprise palette; suits financial and government contexts

Colour rules — apply regardless of theme:

1. Maximum 6–7 distinct colours per chart — beyond that, use grouping or small multiples.
2. Signal colours (red = bad, green = good, amber = warning) are reserved for status encoding only.
3. Colour is never the only encoding for critical distinctions — always pair with shape, dash, or pattern. See references/colourblindness.md.
4. Sequential palettes for ordered/continuous data; diverging palettes for data with a meaningful midpoint.
5. Never hard-code hex values inline — import from a central colours.py module.

---

Step 4 — Layout and composition

Read references/layout-principles.md for grid recipes and typography scale.

• Use dbc.Container / dbc.Row / dbc.Col from dash-bootstrap-components for all grid work.
• F-pattern reading order: most important content top-left. KPI cards → primary chart → supporting charts.
• Wrap every chart in dbc.Card with consistent internal padding (p-3).
• Consistent chart heights within a row — mixed heights break visual rhythm.
• White space is structural, not waste.
• Infographic titles state the insight, not the chart type: "Revenue grew 34% after the Q2 pricing change" not "Revenue over time".

---

Step 5 — Plotly template

Register a named template once in app.py before the layout import. Every figure inherits it automatically.

Fill palette values from colours.py for the selected theme. Full per-theme template code is in references/colour-theory.md.

import plotly.graph_objects as go
import plotly.io as pio
from colours import PALETTE, SURFACE, TEXT_PRIMARY, TEXT_MUTED, GRID, HOVER_BG, HOVER_BORDER

pio.templates["project_theme"] = go.layout.Template(
    layout=go.Layout(
        font=dict(family="Inter, system-ui, sans-serif", size=13, color=TEXT_PRIMARY),
        paper_bgcolor="rgba(0,0,0,0)",   # transparent — card handles background
        plot_bgcolor=SURFACE,
        colorway=PALETTE,
        margin=dict(l=40, r=20, t=55, b=40),
        title=dict(
            font=dict(size=16),          # use html.B() in title string for bold — weight is not a valid Plotly font property
            x=0.0,
            xanchor="left",
        ),
        xaxis=dict(gridcolor=GRID, linecolor=GRID,
                   tickfont=dict(size=11, color=TEXT_MUTED), zeroline=False),
        yaxis=dict(gridcolor=GRID, linecolor=GRID,
                   tickfont=dict(size=11, color=TEXT_MUTED), zeroline=False),
        legend=dict(orientation="h", y=1.02, x=0,
                    bgcolor="rgba(0,0,0,0)", borderwidth=0),
        hoverlabel=dict(bgcolor=HOVER_BG, bordercolor=HOVER_BORDER,
                        font=dict(size=12, color=TEXT_PRIMARY)),
    )
)

pio.templates.default = "project_theme"

Chart functions live in components/charts.py and are pure: DataFrame in, go.Figure out — no side effects, no globals, no Dash logic inside figure functions.

---

Step 6 — Project structure

project/
├── app.py              # Dash init, template registration, server export
├── layout.py           # Full app layout
├── callbacks.py        # All @callback functions
├── colours.py          # Single source of truth for all colour constants
├── components/
│   ├── charts.py       # Pure figure-building functions
│   └── cards.py        # KPI cards and reusable UI components
├── data/
│   └── loader.py       # Data loading, preprocessing, caching
└── assets/
    └── custom.css      # Minimal overrides only

---

Step 7 — Performance

Read references/performance.md before building against real data at scale. Minimum requirements:

• Server-side aggregation — never send row-level data to the browser when aggregated data suffices
• Cache expensive loader functions (Flask-Caching or functools.lru_cache)
• WebGL traces (go.Scattergl, go.Heatmapgl) for > 10k data points
• dcc.Loading wrapper on every chart that involves a data fetch callback
• Empty-state handling in every callback — never return a blank figure without a user-facing message

---

Step 8 — Interaction design

Read references/interaction-design.md for full rules. Core principles:

• The default view must answer the primary question with zero interaction.
• Filters go above the charts they affect — never below.
• Maximum 3 filter controls on a single view before reconsidering the dashboard scope.
• Use drill-down when detail replaces the summary; cross-filter when users compare sub-populations.
• dcc.Store for shared state — never global Python variables in callbacks.
• One callback per logical interaction; return dash.no_update for unchanged outputs.

---

Step 9 — Formatting and localisation

Read references/formatting.md for full conventions. Non-negotiable defaults:

• Dates: DD Mon YYYY (e.g. 15 Jan 2024) — never ambiguous MM/DD/YY
• Timestamps: single named timezone throughout; label it in the axis title or chart subtitle
• Currency: symbol prefix, thousands separator, 2dp for transactions, 0–1dp for aggregated totals (£4.2M)
• Percentages: 1 decimal place (68.3%)
• Large numbers: abbreviate at 1K / 1M / 1B thresholds — define the breakpoints in formatting.py

---

Step 10 — Pre-ship checklist

All boxes must be checked before release.

Data correctness

□ Key metrics reconciled against source of truth
□ Filters tested for empty results — empty state handled gracefully
□ Date range edge cases tested (first day, last day, single day)
□ Aggregations spot-checked against raw data for a known sample

Visual and UX

□ Primary question answered in < 3 seconds on default view
□ Chart titles state the insight, not the chart type
□ Axis labels include units where not obvious from context
□ hovertemplate set on all traces (value + label + unit)
□ Consistent chart heights within each row
□ Filters positioned above the charts they affect
□ Empty-state message shown when a filter returns no data
□ Layout checked at 375px mobile viewport width

Accessibility

□ Colour is not the only encoding for any critical distinction
□ Red/green signal pairs have redundant encoding (shape / dash / pattern)
□ WCAG AA contrast met for all text (4.5:1 normal, 3:1 large/bold)
□ config={"responsive": True} on all dcc.Graph components
□ Tab order is logical — filters before charts, charts in reading order
□ Key chart insights have a visible text summary (not hover-only)
□ Simulated under deuteranopia — no information is lost

Code quality

□ No hex colour literals inline — all colours imported from colours.py
□ All chart functions are pure (DataFrame in, Figure out)
□ No global mutable state in callbacks
□ dcc.Loading on all data-fetch callbacks
□ weight not used in any Plotly font dict

---

Reference files

File	When to read
references/chart-selection.md	Choosing chart type, edge cases, anti-patterns
references/colour-theory.md	Theme selection, full palette library, per-theme template code
references/colourblindness.md	CVD simulation, redundant encoding, contrast checking, keyboard/screen-reader
references/layout-principles.md	Grid recipes, typography scale, infographic anatomy
references/data-quality.md	Pre-design data checks, missingness, outliers, metric definitions
references/performance.md	Large data, WebGL, caching, callback memoization
references/interaction-design.md	Filter rules, drill-down vs cross-filter, control count limits
references/formatting.md	Dates, timezones, currency, number abbreviation conventions
references/observability.md	Structured logging, callback timing, error handling patterns
references/testing.md	Figure function tests, callback integration tests, snapshot regression
references/validation.md	Pre-ship QA checklist, value reconciliation, axis/unit sanity checks