Powerbi Report CLI

Visual Design Cookbook

This section tells you exactly how to configure each visual type for a polished report. These are DESIGN instructions — for PBIR file mechanics, consult the authoring mode.

Contents

• Theme vs Per-Visual — What Goes Where

• Visual-Type Sanity Checks

• Bar & Column Charts

• Line Charts

• Card Visuals

• Tables

• Matrix

• Slicers (continued in visual-cookbook-part-02.md)

• Temporal slicer decision matrix (continued in visual-cookbook-part-02.md)

• Textbox (continued in visual-cookbook-part-02.md)

• Shape (continued in visual-cookbook-part-02.md)

• Scatter (continued in visual-cookbook-part-02.md)

• Waterfall (continued in visual-cookbook-part-02.md)

• Treemap (continued in visual-cookbook-part-02.md)

• Conditional Formatting — MANDATORY (continued in visual-cookbook-part-02.md)

Theme vs Per-Visual — What Goes Where

The report theme should handle these defaults automatically:

• Table/matrix: row banding, header styling, grow-to-fit

• Bar/column: data labels on, value axis hidden, gridlines hidden, bar borders off

• Card: bold values, show labels, tight spacing

• Line chart: smooth curves, shaded area, sparse labels

• Slicer: header/items font sizing

• Global: hidden visual headers, hidden drop shadows

Theme/per-visual boundary — some visual treatments are part of the design but may require per-visual implementation rather than theme-only changes. Record these requirements in the brief; the authoring mode owns the exact PBIR JSON mechanics.

Visual-Type Sanity Checks

Use references/design/chart-selection.md to choose the visual type from the analytical question first. Use this table only as a quick sanity check before configuring the selected visual.

Bar & Column Charts(barChart, clusteredBarChart, columnChart, clusteredColumnChart)

When to use: Comparison across categories (bar = horizontal, column = vertical). Horizontal bars are the DEFAULT for categorical comparison — they handle long labels and >7 categories gracefully. Minimum 6 categories — with ≤5, use a donut (part-to-whole) or stacked bar (composition) instead; bar charts look sparse and the gradient pattern is ineffective at low cardinality.

Design rules:

• ALWAYS sort by value descending (biggest bar at top/left) via sortDefinition unless the axis has a natural order (Date column or numeric column — NOT text month/quarter names, which sort alphabetically in PBI)

• ALWAYS show data labels (labels.show: true, position: OutsideEnd) — eliminates the need for value axis gridlines

• When data labels are on, HIDE the value axis (valueAxis.show: false) and its gridlines (gridlineShow: false) — they're redundant

• Value-gradient coloring — single-measure bar charts render all bars in one color by default. Apply a dataPoint.fill FillRule gradient so the highest-value bar is the darkest and the lowest is the lightest — this reinforces the sort order visually. Use linearGradient2 with dataViewWildcard: { matchingOption: 0 } selector. Pick colors from the theme's dataColors array: light tint for min, base color for max. Each chart on the page gets a different hue — assign palette colors by visual reading order and never reuse a hue already used by cards on the same page.

  • ⚠️ FillRule gradient color stops MUST use Literal hex values — ThemeDataColor silently renders black inside FillRule. Compute tint/shade from dataColors[N].

  • Gradient works best when max/min value ratio is ≤10×. With extreme skew (one dominant outlier), consider a TopN filter or separate the outlier as a card callout.

• For clustered bars (AC vs PY), use contrasting palette colors (e.g., amber + teal, not two blues)

• Category axis: 10pt, muted grey (#605E5C), no title, innerPadding: 30 for comfortable spacing between bars

• Set valueAxis.start to 0 for bars — NEVER truncate the baseline

• Hide bar borders: dataPoint.borderShow: false for a cleaner look

• Hide legend when the category axis already shows the names (redundant); show when a separate Series field provides additional grouping

Theme handles (via visualStyles.barChart["*"]):

• labels show + position + fontSize

• valueAxis hidden + gridlines hidden

• categoryAxis styling + innerPadding

• dataPoint borderShow

• legend visibility

Per-visual must set: sort order, color/gradient treatment, title text

Color assignment rule: see references/design/color.md § Color Assignment Strategy. Same measure as a card → match that card's color. Breakdown of a measure → gradient of that color. Different measure → different hue.

Line Charts (lineChart, areaChart)

When to use: Trend over continuous time. ONLY use if ≥3 time points — if ≤2 points, use cards or a column chart.

Design rules:

• Smooth curves: set lineChartType: "smooth" with interpolationSmooth: "monotoneX" — eliminates jagged segments, looks polished

• Shaded area: areaShow: true, areaMatchStrokeColor: true — fills below the line with a transparent version of the line color. Set area transparency to 80-85% via dataPoint.transparency so the area is subtle

• Line width: 2-3px for hero series (strokeWidth: 2.5), 1px for supporting context lines

• Line color: set via dataPoint.defaultColor — match the card that shows the same measure (see color assignment strategy in color.md)

• Markers: hide at ≥12 data points (clutter). Show at <12 for emphasis. Use circle shape, size 4-5px

• Data labels: sparse, neutral dark (#252423) — never the accent color. Set labelDensity: 25 to show only key inflection points. Position "Above". Do NOT enable label background unless the chart has busy gridlines

• For multi-line: limit to 3-4 series max. Beyond that, use small multiples. If you must show 5+, highlight one in accent and grey the rest

• Reference line: add a y1AxisReferenceLine for average/target — dashed gray (#A19F9D), width 1.5, with dataLabelText: "ValueAndName". This gives context ("is this year above or below normal?")

• Date axis: auto-granularity is usually fine; override to month/quarter/year based on the data range. Never use text month/quarter names (e.g., "January", "Q1") as the Category — they sort alphabetically. Use a Date column or numeric Month Number column instead.

• Gridlines: subtle dotted lines on the value axis help track values; category axis gridlines usually off

Theme handles (via visualStyles.lineChart["*"] in base.json):

• lineStyles: smooth interpolation, stroke width

• categoryAxis / valueAxis: label color, gridline style

• labels: show, sparse density

• legend: hidden for single-series

Per-visual must set: dataPoint.defaultColor (match card color), lineStyles.areaShow, y1AxisReferenceLine (if adding average/target), VCO title text

Formatting objects: lineStyles (strokeWidth, lineChartType, interpolationSmooth, areaShow, areaMatchStrokeColor, showMarker, markerShape, markerSize), dataPoint (defaultColor, transparency), labels (show, labelPosition, labelDensity, fontSize, color), y1AxisReferenceLine (show, value, style, lineColor, dataLabelShow), categoryAxis, valueAxis, legend, trend, forecast, zoom

Card Visuals (cardVisual)

When to use: Single headline metric. Always use cardVisual — card (legacy) is deprecated.

Design rules:

• Cards should show enough context to avoid bare-number ambiguity. Use referenceLabel or a concise contextual subtitle when it adds comparison, coverage, or time-window meaning: "+12% vs Q2 ▲" or "across 3 subjects".

• Give each card a distinct accent color from the palette — creates visual rhythm

• Left accent bar (accentBar) in the card's accent color adds polish

• No internal border (outline.show: false) — must be per-visual, NOT theme

• Clean label text — override label.text with human-readable name

• Cards should be compact: height is generated as the content minimum for the value + label fonts (roughly 11–15% of page height), never hardcoded or padded out to avoid clipping. Follow the Card Sizing formula in the the authoring mode — it scales the fonts to the canvas, sizes height to the content, and caps it so cards never crowd out other visuals. Too tall (150px+) leaves dead space inside the card.

• Do not use a bare one-measure card as the page hero or largest visual. A card can be visually prominent only when it is part of a composite KPI treatment: value + delta/reference label, sparkline or threshold band, and a nearby explanation of why the number matters. Otherwise, move the card into a KPI strip/side callout and give the hero space to a trend, ranked driver chart, variance chart, map, table, or decomposition visual.

Proportional sizing (adapt to any canvas):

• Width: ~23% of page width per card (4 across with ~1.25% gutters)

• Height: generated by that Card Sizing formula (content minimum for the derived fonts, ~11–15% of page height)

• Example at 1280×720: w=296, gutters=16 (height from the formula)

• Example at 1920×1080: w=448, gutters=24 (height from the formula)

• Read page.json width/height first, then compute coordinates

Theme handles (via visualStyles.cardVisual):

• value.bold: true — callout numbers are bold by default

• label.show: true — category label visible by default

Per-visual MUST set (via visual.objects — theme cannot cascade these):

• outline (id: "default"): show: false — removes internal card border

• accentBar (id: "default"): show: true, position: "Left", width: 4D, color = card's accent from palette

• layout (id: "default"): topOuterMargin: 0L, bottomOuterMargin: 0L, leftOuterMargin: 0L, rightOuterMargin: 0L, paddingUniform: 0L — eliminates the gap between card border and content so the accent bar sits flush against the edge

• value (id: "default"): fontSize: 32D, fontColor = accent color

• label (id: "default"): text = human-readable override, fontSize: 10D, fontColor: #605E5C

• padding (id: "default"): Custom, leftMargin: 12L (breathing room from accent bar), rightMargin: 8L, topMargin: 0L, bottomMargin: 0L — top/bottom must be 0 for the accent bar to sit flush (combined with layout outer margins)

• cardCalloutArea: paddingUniform: 0L

VCO settings (can be theme or per-visual):

• padding: top: 0, bottom: 0, left: 0, right: 0 (zero — accent bar runs full height)

• spacing: customizeSpacing: true, verticalSpacing: -6D (tighten label-to-value)

• border: show: true, color: #E8E8E8, radius: 8D (outer rounded container)

• background: show: true, color: #FFFFFF, transparency: 0D

• visualHeader: show: false

• title: show: false (category label IS the title)

⚠️ VCO mixing caveat: If you set ANY VCO property per-visual (background, border, visualHeader), also set padding per-visual in the same visualContainerObjects block. Otherwise PBI may reset padding to its default (~5px) instead of inheriting from the theme.

⚠️ Key limitation: outline, accentBar, layout, and padding use instance selectors (id: "default") and do NOT cascade from theme visualStyles. They must be set per-visual in visual.objects.

Tables (tableEx)

When to use: Detail lookup — when the audience needs to read specific values, not detect patterns. Use tableEx (modern), not table (legacy).

Design rules:

• ALWAYS set grow-to-fit: columnHeaders.autoSizeColumnWidth: true, columnHeaders.columnAdjustment: "growToFit"

• Column headers: bold, slightly darker background (#F3F2F1), 10-11pt

• Values: 10pt, right-align numeric columns, left-align text

• Alternating row colors: use values.backColorPrimary (#FFFFFF) and backColorSecondary (#FAFAFA) — subtle, NOT zebra stripes. MUST also set fontColorPrimary and fontColorSecondary or text goes invisible

• Sort by the most interesting column descending (highest enrollment, worst performance, etc.)

• Conditional formatting: add data bars (dataBar CF) on the primary numeric column — makes magnitudes scannable without reading numbers

• If table has a status/result column, add icon set CF (iconRule) — ✓/✗ or traffic light icons

• Limit visible rows: if the underlying data has >20 rows, add a page-level or visual-level Top N filter

• Total row: show for additive measures (Sum of Revenue), hide for non-additive (Average, %)

Formatting objects: columnHeaders (autoSizeColumnWidth, columnAdjustment, bold, backColor, fontColor, fontSize), values (fontSize, fontColor, backColorPrimary, backColorSecondary, fontColorPrimary, fontColorSecondary), total (show, bold, backColor), grid (gridlineColor, rowPadding)

Sizing:

• Minimum height: 240px — shows ~8 data rows with styled header + banding

• Preferred: 280–320px for detail-heavy tables

• If the table is the bottom visual, expand height to fill remaining canvas rather than leaving whitespace below

• Full-width tables should span 1232px (12 columns) — if slicers are inline with the title, the table gets the full width

Matrix (pivotTable)

When to use: Cross-tabulation with row and column grouping. Use pivotTable (modern), not matrix (legacy).

Design rules:

• Same grow-to-fit and alternating rows as tableEx

• Row headers: bold, left-aligned

• Column headers: bold, centered

• Subtotals: show for the dimension the audience cares about; position at top/bottom based on reading convention

• Stepped layout for hierarchies — indent child rows under parent

• Conditional formatting: background color gradient (fillRule CF) on the values cells — makes the heatmap pattern visible

• Expand/collapse: set expansionStates for the default view — usually expand the first level, collapse deeper levels

Formatting objects: Same as tableEx plus rowHeaders (bold, fontSize), subTotals (show, bold, backColor), columnSubtotals, columnHeaders