Sightline — working on this theme with Claude

This file is for coding agents (Claude Code and others) and for people who edit the theme through one. It covers the workflow, the rules that keep the theme consistent, and the Power BI traps that cost real time to find. docs/reference.md is the full reference.

What this repo is

A Power BI report theme compiled from design tokens. Light and dark variants are built from the same templates and checked by two gates before they are written.

src/variables.json        design tokens (light). Every colour, radius, size lives here
src/themes/dark.json      dark overrides, deep-merged over variables.json
src/theme.json           theme root (name, top-level colours, schema version)
src/text.json            textClasses, referenced as "{{text.<class>.<prop>}}"
src/visuals/global.json  the wildcards: base font, container chrome, axes, legend
src/visuals/<type>.json  one file per visual type: what differs, plus named presets
src/definitions/**       shared fragments, referenced as "{{def.chart.legend}}" etc.
scripts/lib/tokens.js    token loading and the strict template resolver
scripts/build.js         compile, gate, then write dist/theme.json, dist/theme.dark.json
scripts/validate.js       gate 1: JSON schema
scripts/lint-design.js    gate 2: contrast, palette, surfaces, typography
pbi/Preview.pbip          preview report showing every visual with the theme
docs/                    reference, screenshots, cover art, parked experiments

The loop

  1. Edit src/. Never edit dist/ or the theme copy inside pbi/…/RegisteredResources/.
  2. npm run build. It downloads the schema on first run, builds both variants and runs both gates on each. A failure stops with the file and JSON path, and dist/ stays untouched. Run npm run format before you finish; CI runs format:check.
  3. Check it in Power BI (see Verify in Power BI). The gates cannot see rendering, and a property can pass both gates and still be ignored by Power BI.

Rules

Power BI traps

Each of these looked like a theme bug and was not, or looked fine and was broken.

Verify in Power BI

Manual: open pbi/Preview.pbip in Power BI Desktop, then View → Themes → Browse for themes and pick dist/theme.json. Click Refresh once after cloning, because the data cache is not in the repo.

Scripted: the Power BI authoring plugin for Claude Code (powerbi-authoring) brings two CLIs, powerbi-desktop (open, reload, screenshot) and powerbi-report-author (validate, formatting lookup). If they are installed:

  1. Copy dist/theme.json into pbi/Preview.Report/StaticResources/RegisteredResources/ under a new filename (Desktop caches by filename). Set the copy's internal "name" to exactly that filename including .json, update both references in pbi/Preview.Report/definition/report.json (themeCollection.customTheme.name and the RegisteredResources item), and delete the old file.
  2. powerbi-report-author validate pbi/Preview.Report. These findings are known and accepted: PBIR_THEME_VISUAL_PROP_UNKNOWN for padding.* on cardVisual and advancedSlicerVisual, PBIR_FORMATTING_OBJECT_UNKNOWN for slicer.dropdown, PBIR_THEME_VISUAL_UNKNOWN and PBIR_VISUAL_TYPE_UNKNOWN for ganttChart, PBIR_FORMATTING_PROP_UNKNOWN for categoryAxis.autoExpand, PBIR_SCHEMA_UNREACHABLE, and the warning PBIR_SLICER_HEADER_MAY_CLIP. Anything else is a real error.
  3. powerbi-desktop reload, then screenshot the affected pages. A screenshot taken right after a reload can be blank or half-drawn, so take it twice before judging. Compare measurements only within one image, because the window size changes between screenshots.
  4. Use powerbi-report-author formatting search <visualType> <regex> to find the real name of a property before guessing one.

To check that a refactor changes nothing, screenshot every page before and after and compare the images pixel by pixel. Map pages differ between any two shots because tiles load late; re-shoot them before reading anything into it.

To test many variants at once, add a temporary page with one visual per variant, screenshot it, and remove the page again (folder under definition/pages/ plus its entry in pages.json). Do not leave test pages or inline hex colours in the preview report.

Housekeeping