Skip to content
Skills Library
Data & analytics · Review & audit

modifying-theme-json

/modifying-theme-json

Design, enforce, audit and validate Power BI report themes. Invoke when a report uses the default or a minimal theme or its visuals carry many local formatting overrides, or the user asks to create, copy, apply, audit, standardize or validate a theme, push formatting to it, clear visual overrides, or set theme colors, typography, text classes, visual-type overrides or style presets.

Licence
GPL-3.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
63
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

Design, enforce, audit and validate Power BI report themes. Invoke when a report uses the default or a minimal theme or its visuals carry many local formatting overrides, or the user asks to create, copy, apply, audit, standardize or validate a theme, push formatting to it, clear visual overrides, or set theme colors, typography, text classes, visual-type overrides or style presets.

Original author description

Design, enforce, audit and validate Power BI report themes. Invoke when a report uses the default or a minimal theme or its visuals carry many local formatting overrides, or the user asks to create, copy, apply, audit, standardize or validate a theme, push formatting to it, clear visual overrides, or set theme colors, typography, text classes, visual-type overrides or style presets.

How it works

  1. Why Themes Matter
  2. The Formatting Hierarchy
  3. Workflow: Audit Theme Compliance
  4. Workflow: Enforce Theme (Clear Overrides)
  5. Workflow: Author or Modify a Theme
  6. Workflow: Promote Bespoke Formatting to Theme
  7. Workflow: Validate a Theme
  8. Schema and Documentation
  9. Theme Top-Level Keys
  10. References
Original SKILL.md headings · 322 lines, 2,325 words
SKILL.md preview
---
name: modifying-theme-json
version: 26.40.3
description: Design, enforce, audit and validate Power BI report themes. Invoke when a report uses the default or a minimal theme or its visuals carry many local formatting overrides, or the user asks to create, copy, apply, audit, standardize or validate a theme, push formatting to it, clear visual overrides, or set theme colors, typography, text classes, visual-type overrides or style presets.
---

# Power BI Report Themes

## Why Themes Matter

A report without a well-designed theme accumulates formatting debt. Every visual ends up with its own bespoke title size, shadow toggle, border style, and hardcoded colors in `visual.json`. This creates three problems:

1. **Inconsistency.** Visuals drift apart as authors format each one individually. One card has 14pt titles, another has 12pt; one chart has shadows, another doesn't. The report looks unfinished.
2. **Fragility.** Rebranding or updating the visual style means touching every visual.json individually. A report with 40 visuals across 8 pages means 40 files to edit. With a theme, it's one file.
3. **Bloated visual JSON.** Each bespoke override adds lines to visual.json, making reports harder to diff, review, and maintain. A clean visual.json should contain field bindings, position, and conditional formatting; everything else should come from the theme.

Reports using the default Power BI theme or a minimal custom theme (just `dataColors` and a name) are leaving most formatting to Power BI's built-in defaults, which change between Desktop releases. A well-designed theme locks in the intended appearance.

**Signs a theme needs attention:**
- Many visuals have `objects` or `visualContainerObjects` with redundant formatting
- Visuals of the same type look inconsistent (different title fonts, shadows on some but not others)
- The theme JSON has few or no `visualStyles` entries
- The report uses a built-in theme like "Default" or "Classic" without customization

> **Tooling preference:** Use `pbir` CLI when available (`pbir theme colors`, `pbir visuals clear-formatting`). Fall back to direct `jq` modification when unavailable. Always validate after every write.

> **Tip:** Theme JSON files can be 75KB+ and 2000+ lines. Do not read the full monolithic file. Use `pbir theme serialize` to split into small editable files (see Author/Modify workflow below), or use `jq` to extract only specific keys. Serialized fragments from the serialize/build workflow are small and safe to read directly.

For PBIR JSON mechanics (property names, filter pane selectors, ThemeDataColor syntax, `jq` patterns), see the **`pbir-format`** skill (pbip plugin) -> `references/theme.md`.

## The Formatting Hierarchy

Power BI applies visual formatting through a four-level cascade. Each level overrides the level above it:

```
Level 1  Power BI built-in defaults
         |
Level 2  Theme wildcard     visualStyles["*"]["*"]           applies to ALL visuals
         |
Level 3  Theme visual-type  visualStyles["lineChart"]["*"]   overrides wildcard for that type
         |
Level 4  Visual instance    visual.json objects +            overrides everything
                            visualContainerObjects
```

A visual that selects a named style preset adds a step between levels 3 and 4: the preset
(`visualStyles["<type>"]["<preset>"]`) overrides the type's `"*"` style, and level 4 still wins over
it. See **`references/style-presets.md`**.

### Core Principle

Push as much formatting as possible into levels 2 and 3. A well-designed theme means:

- Visual JSON files stay lean — no bespoke formatting noise cluttering visual.json
- Global style changes require editing one file
- New visuals automatically inherit correct defaults without manual intervention

Visual-level overrides (level 4) should exist only for true one-offs: content-specific formatting, exceptions to the visual-type default, or conditional formatting expressions.

### Diagnosing Why a Visual Looks the Way It Does

When a visual renders unexpectedly, walk up the cascade:

1. Check `visual.json` → `objects` and `visualContainerObjects` (level 4 always wins)
2. Check the named style preset the visual selects (`visualContainerObjects.stylePreset`), then theme `visualStyles["<type>"]["*"]` for that visual type (level 3)
3. Check theme `visualStyles["*"]["*"]` wildcard (level 2)
4. If absent everywhere, Power BI is applying a built-in default

## Workflow: Audit Theme Compliance

Use when assessing whether a report's visuals are inheriting from the theme or have accumulated stale overrides.

**Step 1 — Locate the custom theme:**
```bash
THEME_NAME=$(jq -r '.themeCollection.customTheme.name' Report.Report/definition/report.json)
THEME="Report.Report/StaticResources/RegisteredResources/$THEME_NAME"
```

**Step 2 — Review what the theme sets at wildcard level:**
```bash
# Preferred
pbir theme colors "Report.Report"
pbir theme text-classes "Report.Report"

# Fallback
jq '.visualStyles["*"]["*"] | keys' "$THEME"
```

**Step 3 — Continue with full audit process** — see **`references/theme-compliance.md`** for the complete workflow: scanning all visuals for bespoke overrides, classifying stale vs intentional vs CF, severity levels, and fix decision tree.

## Workflow: Enforce Theme (Clear Overrides)

After applying a new theme or making significant theme changes, stale visual-level overrides prevent the new theme from rendering correctly.

**With `pbir` CLI (preferred):**
```bash
# Clears bespoke formatting while preserving conditional formatting expressions
pbir visuals clear-formatting "Report.Report/**/*.Visual" --keep-cf -f
```

**With `jq` (manual, per-visual):**
```bash
# Safe: clear container chrome only (title, border, background, shadow, padding)
# Does NOT touch chart-specific objects or conditional formatting
jq 'del(.visual.visualContainerObjects)' visual.json > tmp && mv tmp visual.json

# Aggressive: clear everything including chart-specific overrides
# WARNING: also removes conditional formatting — only use if CF is confirmed absent
jq 'del(.visual.objects) | del(.visual.visualContainerObjects)' visual.json > tmp && mv tmp visual.json

# Always validate after
jq empty visual.json
```

> When in doubt, clear `visualContainerObjects` only. Leave `objects` unless you have confirmed no conditional formatting exists in that visual.

### Switching to a Different Theme (Re-Theming)

Swapping a report from one theme to another is a migration, and editing only the theme JSON leaves **theme residue**: surviving level-4 overrides that still win at the cascade, plus colors that were correct under the old polarity and break (often invisible text) under the new one. Re-theming sits between apply and enforce: build an old-to-new color map first, then apply the theme, sweep overrides, remap surviving literals, and run the polarity gate so foreground text survives the new background. See **`references/re-theming.md`**.

## Workflow: Author or Modify a Theme

When building or substantially revising a theme, use the **serialize/build workflow** via `pbir` CLI. This splits the monolithic theme JSON into small, focused files that are easy to read and edit without loading 2000+ lines of JSON into context.

### Serialize/Build Workflow (Recommended)

> **IMPORTANT:** Serialize to a temporary folder outside the `.Report/` directory. The PBIR validation hooks monitor `.Report/` for JSON changes and will flag the serialized fragments as invalid PBIR files. Use `/tmp/`, a sibling folder, or the `-o` flag to place the `.Theme` folder elsewhere.

**Step 1 — Serialize the theme into editable files:**
```bash
# From a report (outputs to a .Theme folder)
pbir theme serialize "Report.Report" -o /tmp/MyTheme.Theme

# From a standalone theme JSON file
pbir theme serialize theme.json -o /tmp/MyTheme.Theme
```

This produces small, focused files: `_config.json` (colors, text classes, named colors), `_wildcards.json` (wildcard visual styles), and one file per visual-type override (e.g., `slicer.json`, `page.json`).

**Step 2 — Edit the serialized files.** Each file is small enough to read and edit directly. Focus on:
1. `_config.json` — `dataColors`, semantic colors, `textClasses`, background/foreground variants
2. `_wildcards.json` — container defaults (title, border, shadow, padding)
3. Visual-type files — overrides for specific types (textbox, image, card, etc.)

**Step 3 — Build and apply back to the report:**
```bash
# Build only (produces a merged theme.json)
pbir theme build /tmp/MyTheme.Theme

# Build and apply directly to the report
pbir theme build /tmp/MyTheme.Theme -o "Report.Report" -f --clean
```

The `--clean` flag removes the `.Theme` folder after building.

### Quick Modifications (No Serialize Needed)

For small, targeted changes, use the CLI directly without serializing:

```bash
pbir theme set-colors "Report.Report" --good "#00B050" --bad "#FF0000"
pbir theme set-text-classes "Report.Report" title --font-size 14 --font-face "Segoe UI Semibold"
pbir theme set-formatting "Report.Report" "*.*.dropShadow.show" --value false
```

See the **`pbir-cli`** skill → `references/modifying-theme.md` for full CLI command reference.

### Design Sequence

Whether using serialize/build or direct CLI commands, follow this order:

1. **Start from a valid base.** Use a template (`pbir theme apply-template`), the SQLBI/Data Goblins theme, or a [community template](https://github.com/deldersveld/PowerBI-ThemeTemplates). Do not author from an empty `{}`.
2. **Design the color system first** (`dataColors`, semantic colors, background/foreground variants). Color decisions cascade everywhere.
3. **Set typography** (`textClasses`) — font face and size for `title`, `header`, `label`, `callout`, `dataTitle`. Stick to Segoe UI / Segoe UI Semibold; custom fonts will not render on other users' machines.
4. **Set wildcard container defaults** (`visualStyles["*"]["*"]`): title visibility/font/size, `dropShadow.show: false`, padding, border, filter pane.
5. **Add visual-type overrides** for types that differ from the wildcard — at minimum, `textbox` and `image` to suppress title/border/background/shadow.
6. **Validate** with `pbir theme validate "Report.Report"`, deploy, and visually verify.

For detailed design guidance, see **`references/theme-authoring.md`**. For visual-type override patterns, see **`references/visual-type-overrides.md`**.

## Workflow: Promote Bespoke Formatting to Theme

When a `visual.json` has formatting that should become a theme default — either for that visual type or for all visuals — promote it.

**With `pbir` CLI (preferred):**
```bash
# Preview what would be pushed from a well-formatted visual into the theme
pbir theme push-visual "Report.Report/Page.Page/Card.Visual" --dry-run

# Push formatting to theme as the default for that visual type
pbir theme push-visual "Report.Report/Page.Page/Card.Visual"

# Push only specific components (title, background, border, etc.)
pbir theme push-visual "Report.Report/Page.Page/Card.Visual" --components title,background,border
```

**Manual process** (when CLI is unavailable):

1. **Identify** what's in `visual.objects` (chart-specific) and `visual.visualContainerObjects` (container chrome)
2. **Decide** whether it belongs in the wildcard (`["*"]["*"]`) or a visual-type section (`["lineChart"]["*"]`)
3. **Write** the value into the theme, then validate
4. **Remove** the override from the visual, then validate
5. **Verify** the visual still renders correctly

Both `objects` and `visualContainerObjects` properties map to the same `visualStyles[type][state]` section in the theme. The distinction in visual.json doesn't exist in the theme.

For complete property mapping tables, wildcard vs visual-type decision guide, color handling, and batch promotion across many visuals, see **`references/promoting-formatting.md`**.

## Workflow: Validate a Theme

**With `pbir` CLI (preferred):**
```bash
# Validate a report's theme (checks JSON syntax, structure, and completeness)
pbir theme validate "Report.Report"

# Validate a standalone theme file
pbir theme validate "theme.json"

# Validate a serialized .Theme folder before building
pbir theme validate "MyTheme.Theme"
```

**Manual validation** (when CLI is unavailable):
```bash
# 1. JSON syntax
jq empty "$THEME" && echo "JSON valid"

# 2. Required top-level keys
jq '{dataColors: (.dataColors | type), visualStyles: (.visualStyles | type), textClasses: (.textClasses | type)}' "$THEME"

# 3. Wildcard section
jq 'if .visualStyles["*"]["*"] then "wildcard exists" else "MISSING wildcard" end' "$THEME"

# 4. Valid hex colors
jq '[.dataColors[] | select(test("^#[0-9A-Fa-f]{6}$") | not)]' "$THEME"

# 5. No null visual-type sections
jq '[.visualStyles | to_entries[] | select(.value == null) | .key]' "$THEME"
```

After validation, deploy and visually verify:
- Wildcard container chrome (titles, borders, shadows) applies to all visuals
- Filter pane and filter cards render correctly on all pages
- Visual-type overrides correctly suppress the wildcard for exempt types (e.g., textboxes have no title)
- Data colors cycle correctly on multi-series charts

## Schema and Documentation

The official theme JSON schema, the Microsoft Learn pages on report themes, the community theme
templates and the PBIR item schemas are linked in [`references/schema-and-docs.md`](references/schema-and-docs.md).

Resolve the current schema version at author time rather than hardcoding a number:

```bash
gh api repos/microsoft/powerbi-desktop-samples/contents/"Report Theme JSON Schema" \
  --jq '.[].name' | sort | tail -1
```

### IDE Integration (`$schema`)

Add a `$schema` property to the theme JSON to enable autocomplete and validation in VS Code. Use the versioned raw GitHub URL, not the generic `powerbi.com` marker:

```json
{
  "$schema": "https://raw.githubusercontent.com/microsoft/powerbi-desktop-samples/main/Report%20Theme%20JSON%20Schema/reportThemeSchema-2.154.json",
  "name": "MyTheme",
  "dataColors": ["#1971c2", "..."]
}
```

Power BI validates an imported theme against the schema baked into the Desktop build. Validation is reject-unknown-fields: one misspelled key refuses the entire theme. A theme passing `jq` validation can still fail Desktop import on a typo. See `references/theme-authoring.md` for the full schema version guidance.

## Theme Top-Level Keys

```yaml
name:          string   # display name shown in Power BI UI
dataColors:    string[] # ordered hex palette for data series

# Semantic CF colors (flat hex keys; CF measures return these names as strings)
good / bad / neutral: string

# Gradient CF colors (flat hex keys; "null" is the key name, not JSON null)
maximum / center / minimum / null: string

# Structural colors (non-data chrome: gridlines, axis labels, filter-card bg, etc.)
# Use level-N names for new themes; CLI alias equivalents shown in parentheses
firstLevelElements:  string  # (foreground)
secondLevelElements: string  # (foregroundNeutralSecondary)
thirdLevelElements:  string  # (backgroundLight)
fourthLevelElements: string  # (foregroundNeutralTertiary)
background:          string
secondaryBackground: string  # (backgroundNeutral)
tableAccent:         string

# Extended surface/foreground palette
foregroundLight / foregroundDark: string
backgroundLight / backgroundNeutral / backgroundDark: string

textClasses:   object  # typography per semantic role (title, label, callout, header, boldLabel, etc.)
visualStyles:  object  # [visualType][state] formatting cascade
```

For `textClasses`: 4 primary classes you set; 8 secondary classes that derive automatically. See `references/theme-authoring.md`.

For `visualStyles`: named style presets are a second key alongside `"*"` inside a visual-type section; they surface in the Format pane Style dropdown. See `references/advanced-theme-features.md`.

## References

- **`references/theme-authoring.md`** — Color system design (data colors, semantic, structural, null gradient), text class inheritance, `$id` filter-card states, wildcard minimum set, schema version guidance
- **`references/style-presets.md`**: named style presets per visual type, the default preset, selecting a preset on visuals and authoring presets with `pbir`
- **`references/advanced-theme-features.md`** — Named style presets (Format-pane dropdown), base theme layering model, organizational theme distribution, mobile-only formatting overrides
- **`references/serialize-build.md`** — Serialize/build workflow: splitting themes into editable files, editing, rebuilding, validation, temporary folder guidance
- **`references/applying-themes.md`** — Applying templates, post-apply enforcement, clearing visual overrides, normalizing hardcoded colors
- **`references/re-theming.md`** — Switching a report to a new theme without leaving residue: old-to-new color map, inline-override sweep on shapes/textboxes/buttons, the polarity-flip foreground-text sweep, dark-mode checklist, slicer header role-preserving remap
- **`references/copying-themes.md`** — Copying themes between reports, extracting/downloading themes, comparing themes, consolidating across a portfolio
- **`references/promoting-formatting.md`** — Promoting bespoke visual.json formatting to theme: push-visual CLI, objects vs visualContainerObjects, wildcard vs visual-type, property mapping tables
- **`references/theme-compliance.md`** — Systematic audit workflow, stale override classification, severity levels, fix decision tree
- **`references/visual-type-overrides.md`** — Override patterns for textbox, image, shape, card, kpi, slicer, lineChart, barChart, tableEx, and matrix
- **`references/schema-and-docs.md`**: links to the official theme schema, the Microsoft Learn theme pages, community templates and the PBIR item schemas

## Related Skills

- **`pbir-cli`** → `references/modifying-theme.md` — Full CLI command reference for theme operations (serialize/build, set-colors, set-text-classes, set-formatting, push-visual, fonts, background, icons, diff)
- **`pbir-cli`** → `references/apply-theme.md` — Applying templates, copying themes between reports, clearing visual overrides
- **`pbir-format`** (pbip plugin) — Full theme mechanics: ThemeDataColor syntax, filter pane selectors, jq modification patterns, clearing overrides
- **`pbi-report-design`** — Report design principles: 3-30-300 rule, layout, spacing, color usage, accessibility
Files in this package (63)
  • SKILL.md 18 KB
  • examples/DataGoblins2021.json 14 KB
  • examples/Fluent2-CY26SU03.json 87 KB
  • examples/visualTypes/actionButton.md 2 KB
  • examples/visualTypes/advancedSlicerVisual.md 2 KB
  • examples/visualTypes/aiNarratives.md 1 KB
  • examples/visualTypes/areaChart.md 2 KB
  • examples/visualTypes/azureMap.md 2 KB
  • examples/visualTypes/barChart.md 3 KB
  • examples/visualTypes/bookmarkNavigator.md 3 KB
  • examples/visualTypes/card.md 1 KB
  • examples/visualTypes/cardVisual.md 2 KB
  • examples/visualTypes/clusteredBarChart.md 3 KB
  • examples/visualTypes/clusteredColumnChart.md 2 KB
  • examples/visualTypes/columnChart.md 3 KB
  • examples/visualTypes/decompositionTreeVisual.md 3 KB
  • examples/visualTypes/donutChart.md 2 KB
  • examples/visualTypes/filledMap.md 2 KB
  • examples/visualTypes/filter.md 1 KB
  • examples/visualTypes/funnel.md 2 KB
  • examples/visualTypes/gauge.md 2 KB
  • examples/visualTypes/group.md 1 KB
  • examples/visualTypes/hundredPercentStackedAreaChart.md 2 KB
  • examples/visualTypes/hundredPercentStackedBarChart.md 3 KB
  • examples/visualTypes/hundredPercentStackedColumnChart.md 3 KB
  • examples/visualTypes/image.md 1 KB
  • examples/visualTypes/keyDriversVisual.md 2 KB
  • examples/visualTypes/kpi.md 2 KB
  • examples/visualTypes/lineChart.md 2 KB
  • examples/visualTypes/lineClusteredColumnComboChart.md 2 KB
  • examples/visualTypes/lineStackedColumnComboChart.md 2 KB
  • examples/visualTypes/listSlicer.md 2 KB
  • examples/visualTypes/map.md 2 KB
  • examples/visualTypes/multiRowCard.md 2 KB
  • examples/visualTypes/pieChart.md 2 KB
  • examples/visualTypes/pivotTable.md 3 KB
  • examples/visualTypes/pythonVisual.md 2 KB
  • examples/visualTypes/qnaVisual.md 3 KB
  • examples/visualTypes/rdlVisual.md 2 KB
  • examples/visualTypes/ribbonChart.md 3 KB
  • examples/visualTypes/scatterChart.md 2 KB
  • examples/visualTypes/scorecard.md 2 KB
  • examples/visualTypes/scriptVisual.md 2 KB
  • examples/visualTypes/shape.md 1 KB
  • examples/visualTypes/shapeMap.md 1 KB
  • examples/visualTypes/slicer.md 2 KB
  • examples/visualTypes/stackedAreaChart.md 2 KB
  • examples/visualTypes/tableEx.md 2 KB
  • examples/visualTypes/textSlicer.md 2 KB
  • examples/visualTypes/textbox.md 1 KB
  • examples/visualTypes/treemap.md 2 KB
  • examples/visualTypes/waterfallChart.md 3 KB
  • references/advanced-theme-features.md 6 KB
  • references/applying-themes.md 5 KB
  • references/copying-themes.md 4 KB
  • references/promoting-formatting.md 8 KB
  • references/re-theming.md 10 KB
  • references/schema-and-docs.md 1 KB
  • references/serialize-build.md 4 KB
  • references/style-presets.md 4 KB
  • references/theme-authoring.md 19 KB
  • references/theme-compliance.md 8 KB
  • references/visual-type-overrides.md 7 KB

Versions

RepositoryScoreLicence
This page · insightfulanalytics/pbi_agentic_dev100GPL-3.0
data-goblin/power-bi-agentic-development100GPL-3.0

Database snapshot: 13.11.2026 · package version 841a400d18e9 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100power-bi-theme
    Browse, visually compare and pick Power BI report themes. Use when the user wants to "pick a theme", "see all my themes", "preview themes", "compare themes", "open the theme gallery" or apply a preset theme. Renders every theme in the library as a mock report in an HTML gallery,…
  • 100power-bi-themes
    Apply, inspect, and compare Power BI report themes and conditional formatting rules using pbi-cli. Invoke this skill whenever the user mentions "theme", "colours", "colors", "branding", "dark mode", "corporate theme", "styling", "conditional formatting", "colour scale",…
  • 90Power BI Themes
    Apply, inspect, and compare Power BI report themes and conditional formatting rules using pbi-cli. Invoke this skill whenever the user mentions "theme", "colours", "colors", "branding", "dark mode", "corporate theme", "styling", "conditional formatting", "colour scale",…
  • 100pbir-format
    Format reference for Power BI Enhanced Report (PBIR) JSON schemas and patterns. Automatically invoke when the user asks about PBIR JSON structure, visual.json properties, PBIR expressions, objects vs visualContainerObjects, theme inheritance, conditional formatting patterns,…
  • 90Power BI Report
    Scaffold, validate, preview, and manage Power BI PBIR report projects using pbi-cli. Invoke this skill whenever the user mentions "create report", "new report", "PBIR", "scaffold", "validate report", "report structure", "preview report", "report info", "reload Desktop", "convert…
  • 100power-bi-report
    Scaffold, validate, preview, and manage Power BI PBIR report projects using pbi-cli. Invoke this skill whenever the user mentions "create report", "new report", "PBIR", "scaffold", "validate report", "report structure", "preview report", "report info", "reload Desktop", "convert…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.