report-visualization-design

name

report-visualization-design

description

Design a Power BI report/visualization in the Kurt-Buhler / Bas-Dohmen mold — a checklist-driven method: decide the question first, structure the page with the 3-30-300 information-seeking hierarchy, choose the visual by question-type, design headline KPIs with actual/target/gap + pre-attentive color, lay everything on an 8-pt grid, and tune density / color tokens / accessibility. Emits a layout that maps cleanly onto PBIR (visualType enum + pbir-layout-engine geometry). Used by `power-bi-engineer` (primary).

Report Visualization Design Skill

Purpose: Give power-bi-engineer a concrete, reproducible method for designing a Power BI report that communicates — not just renders. The method distills the published design canon of Kurt Buhler (Data Goblins / SQLBI — the 3-30-300 rule, the "anatomy of an effective KPI visual", pre-attentive color) and the design-first school associated with Bas Dohmen (How to Power BI — decide-first, prototype-then-build, less-is-more). Every step is a checklist item, not an aesthetic opinion, so a design from this skill is directly realizable as PBIR (it names real visualTypes and emits grid-aligned geometry).

Sourcing & honesty. The load-bearing techniques are cited inline with retrieval date 2026-06-08. Where a technique is the broader Power BI design canon rather than a specific named source — or where attribution to a specific person can't be confirmed from a primary source — it is marked [unverified attribution]. The value is the reproducible technique, not the name-drop. Re-verify the volatile bits (visualType strings, schema rules) at use via the PBIR reference below.

When to Use

• Designing a new report/page from a blank canvas — you have a data model and a business question, and need a layout that lands.
• A report "makeover" — an existing report is cluttered, slow to read, or "Power BI slop" (every-field-on-the-page) and needs restructuring.
• Reviewing someone else's report for communication quality — design is a review dimension, the same way performance and DAX-correctness are.
• Before authoring PBIR — run this skill to decide what goes where, then hand the result to pbir-layout-engine to lint the geometry and pbir-enhanced-reference.md to author the JSON.

How this maps onto our PBIR canon (do not duplicate — point at these)

This skill is the design layer. The realization layer already exists in the marketplace; this skill produces inputs for it, it does not re-implement it:

Layer	Owned by	This skill's relationship
Which visualType strings are real + their query roles	knowledge/pbir-enhanced-reference.md § 1 (the visualType enum)	This skill's chart-selection step picks only from that enum (kpi, cardVisual, clusteredBarChart, lineChart, pivotTable, …). Never invent a visual name.
Page geometry — no-overlap / within-canvas / equal-gap / column-alignment + PBIR schema checks	pbir-layout-engine (lint.py)	This skill emits x/y/w/h on an 8-pt grid; run lint.py on the page to prove the grid holds. The helper below produces lint-clean coordinates.
Authoring the visual/page/report JSON (filterConfig, objects vs visualContainerObjects, literal suffixes)	knowledge/pbir-enhanced-reference.md	After this skill decides the design, author the JSON there.
Why a deployed report renders blank	knowledge/pbir-enhanced-report-loading.md	Debug runbook — out of scope here.

The handoff: design here → realize in PBIR there. A design that names a non-enum visual or off-grid geometry is a defect this skill is meant to prevent.

The method — six steps, each a checklist

Step 1 — Decide the question first (decide-first, not data-first)

The single biggest design failure is building around what's in the model instead of what must be decided. Bas Dohmen's framing: "Reports fail for one reason: they're built around what's available in the data, not around what needs to be decided" (datatraining.io/powerbidesigntransformation, retrieved 2026-06-08).

• Write the one decision or question this page answers, as a sentence (e.g. "Are we meeting the orders target, and which regions/products are driving the gap?"). If you can't, the page isn't ready to design.
• List the 3-second takeaway (the headline answer) separately from the drill questions (what the user asks next). These map to the layout tiers in Step 2.
• One page = one question. A second decision is a second page, reached by navigation — not a crowded single page.

Step 2 — Structure the page with the 3-30-300 hierarchy (Buhler)

Kurt Buhler's 3-30-300 rule paraphrases Shneiderman's visual information-seeking mantra ("overview first, zoom and filter, then details-on-demand") into report-design tiers (sqlbi.com — Introducing the 3-30-300 rule, retrieved 2026-06-08):

Tier	User gets… in	Content	Placement (Western reading flow)
3 seconds	an overview of the most important questions/areas	headline KPIs + 1 trend; simple visuals (kpi, cardVisual, lineChart)	top-left, moving right
30 seconds	the ability to filter & zoom to periods/categories	performance-by-dimension bars + slicers; conditional formatting on under-performers	middle-left / center
300 seconds	details-on-demand to inform an action	curated matrix / supplemental table; drillthrough; dynamic links	bottom-right

• Place the 3-second content top-left. Keep it focused on the primary question; resist filling it.
• Group 30-second filter/zoom visuals in the center. Limit to 3-5 key breakdowns — "too many visuals in the filter section creates cognitive overload" (ibid.).
• Put 300-second detail in the bottom-right; prefer a pivotTable / tableEx and drillthrough over dumping a wide table onto the main view.
• The rule also applies across pages: an executive summary is the 3-second view; a category page is the 30-second view; a drillthrough/detail page is the 300-second view. Use cross-report/within-report drillthrough to keep context when zooming (ibid.).

Step 3 — Choose the visual by the question-type, not by taste

Match the chart to the analytical question. These seven shapes cover ~95% of business reporting (tabulareditor.com — Data visualization best practices, retrieved 2026-06-08). Pick the visualType from the PBIR enum § 1:

The question is about…	Use	PBIR visualType
A single headline number + status	KPI card	kpi, cardVisual, card, multiRowCard
Comparing categories	bar / column	clusteredBarChart, clusteredColumnChart
Trend over time	line / area	lineChart, areaChart
Composition (2-3 parts max)	donut (sparingly)	donutChart, pieChart
Change between two points	waterfall	waterfallChart
Relationship between two metrics	scatter (X & Y must be measures)	scatterChart
Detailed/precise values	table / matrix	tableEx, pivotTable
Geographic comparison	map	(per enum — verify at use)

• For each visual on the page, state the question it answers. A visual that doesn't answer a listed question is a candidate to cut.
• Donut/pie only for 2-3 slices. More slices → bar chart.
• Mixed dimension + measure in a table → pivotTable, never tableEx (it silently blanks in Fabric — see the tableEx vs pivotTable callout in pbir-enhanced-reference.md § 1).
• To let users switch the metric/dimension shown, prefer field parameters or calculation groups over duplicate visuals (sqlbi 3-30-300, retrieved 2026-06-08).

Step 4 — Design the headline KPI (Buhler's "anatomy of an effective KPI visual")

A KPI card earns its place only if it answers "is this good or bad, and is it getting better or worse?" without the reader doing arithmetic (data-goblins.com — KPIs and cards in Power BI, retrieved 2026-06-08). It must carry three layers:

• The Number — aggregated, with appropriate units and decimal precision ("only the level of detail necessary"). No default font; match org branding (ibid.).
• The Meaning — a baseline/target (budget, forecast, prior period) and the gap to it. The gap is the most load-bearing element — it answers "good or bad?" pre-attentively (data-goblins, retrieved 2026-06-08).
• The Context — a trend (sparkline / kpi.TrendLine) or small breakdown, only if genuinely useful. "Overwhelming users with information is one of the easiest ways to make your report ineffective" (ibid.).
• Color only to steer attention — neutral when on-target, deep red when off-target (leverages the implicit negative association). Don't color for decoration (ibid.).
• No more than 3-4 KPI callouts across the top — excess dilutes impact (ibid.).
• Use DAX format strings for up/down arrows and signed gaps so status reads instantly (sqlbi 3-30-300, retrieved 2026-06-08). Watch the format-scale trap (0.0\% vs 0.0%) — see pbir-dax-pitfalls.md.
• SVG micro-viz (custom sparkline measures) carry maintenance cost — if you use them, hide/mark the helper measures private so self-service users don't misuse them (data-goblins, retrieved 2026-06-08).

Step 5 — Lay it on an 8-point grid (Dohmen-school precision + our linter)

Disciplined spacing is what separates a "makeover" from a mess. The widely-used Power BI design default is a 1664×936 canvas on an 8-point grid, key metrics in the top-left zone [unverified attribution] (canon summarized at lukasreese.com — dashboard design best practices, retrieved 2026-06-08 — page returned HTTP 403 on direct fetch this session, so the numeric tokens are [unverified — secondary summary]; treat 1664×936 as a sensible default, not gospel).

• Choose a canvas size (default 1664×936 / 16:9) and an 8-px grid module — every x, y, width, height is a multiple of 8.
• Equal gaps between visuals; align columns. These are exactly the checks pbir-layout-engine's check-3 (equal-gap) and check-4 (column-alignment) enforce.
• Use the grid.py helper below to turn a tier-template + visual count into lint-clean x/y/w/h. Then run the linter to prove it: python3 plugins/ravenclaude-core/skills/pbir-layout-engine/lint.py <page.json>.

Step 6 — Tune density, color tokens & accessibility (less-is-more)

The "less is more" / data-ink discipline: think about what you can remove to make the chart simpler, not what you can add to make it nicer (tabulareditor.com, retrieved 2026-06-08).

• Color budget: ≤ 6 colors on a page; more is visual noise [unverified attribution] / canon (lukasreese summary + tabulareditor, retrieved 2026-06-08). Reserve a bright accent for the actionable insight; use subtler/lighter tones for everything else.
• Typography: one type family, a small size scale (e.g. title / KPI-number / label). Avoid eccentric or over-decorated styles (tabulareditor, retrieved 2026-06-08).
• Density: the brain "doesn't handle large amounts of information presented simultaneously very well" — prefer white space and a second page over a crammed one (ibid.).
• Contrast / accessibility: white chart backgrounds on a light-grey page give the contrast step; ensure the message survives any interaction (filtered states must still read correctly so users trust the numbers) (ibid.). Don't encode meaning in color alone — pair red/green with an arrow or sign for color-blind users [unverified attribution] / WCAG canon.
• Data-ink: drop heavy borders, gridlines, and dark table fonts; let the data carry the page (ibid.).
• Quality starts in the semantic model — consistent measure names, formats, and displayFolders prevent business logic scattering across visuals (ibid.; enforced by enforce-measure-metadata.md + the validate-tmdl-measure-metadata.sh hook).

Optional helper — grid.py (8-pt layout solver → PBIR-ready geometry)

grid.py is a stdlib-only, fail-safe coordinate solver. Given a canvas, a margin, a gap, and a chosen 3-30-300 template, it emits each region's x/y/width/height snapped to the 8-pt grid — coordinates that pass pbir-layout-engine's within-canvas / no-overlap / equal-gap / column-alignment checks, ready to drop into a PBIR page.json's position blocks.

python3 plugins/power-platform/skills/report-visualization-design/grid.py --template 3-30-300 --format json
python3 .../grid.py --template kpi-strip --kpis 4 --canvas 1664x936 --format json

Templates: 3-30-300 (overview top-left / filter band / detail bottom-right), kpi-strip (N equal KPI cards across the top), golden-overview (single hero visual + supporting column). It only does arithmetic (no network, no file writes); an invalid request prints a diagnostic to stderr and exits non-zero. Verify the output against the linter before authoring JSON.

Output Contract

When this skill drives a design deliverable, the report ends with the cross-plugin Structured Output JSON block per ../../../ravenclaude-core/skills/structured-output/SKILL.md, plus the Power Platform ## Output Contract lines (Status / Files changed / Gates passed / Open questions / Licensing impact / Grounding checks performed) from the plugin constitution § 6. For a design, Gates passed should cite the pbir-layout-engine lint result on the emitted geometry.