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

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