/deneb-visuals

name: deneb-visuals
description: Deneb visual creation, Vega/Vega-Lite spec authoring, and Deneb best practices for PBIR reports. Automatically invoke whenever the user mentions "Deneb" in any context, or asks about Vega/Vega-Lite specs in Power BI, Deneb cross-filtering, Deneb interactivity, pbiColor theme integration, Deneb field name escaping, or Deneb rendering issues.

Deneb Visuals in Power BI (PBIR)

> **Use `pbir` for every report mutation.** Read PBIR metadata only for diagnosis. If `pbir` is > unavailable or lacks an operation, stop and report the gap; never edit report JSON directly.

Deneb is a certified custom visual for Power BI that enables Vega and Vega-Lite declarative visualization specs directly inside reports. Author specs using this skill.

Provider Policy

**Prefer Vega-Lite** for new Deneb visuals unless specific Vega-only features are required (signals, event streams, custom projections, force/voronoi layouts). Vega-Lite is more concise, easier to maintain, and covers most chart types. For advanced Vega features, see `references/vega-patterns.md` and the [Vega documentation](https://vega.github.io/vega/docs/).

Visual Identity

• **visualType:** `deneb7E15AEF80B9E4D4F8E12924291ECE89A`
• **Bundled runtime:** Vega 6.2.0 / Vega-Lite 6.4.1 (since Deneb 1.8; use `v6.json` schema URLs)
• **Data role:** Single `dataset` role (all fields go into one "Values" well)
• **Default row limit:** 10,000 rows (override via `dataLimit.override`)
• **Provider:** `vegaLite` (default) or `vega` (when Vega-specific features needed)
• **Render modes:** `svg` (default, sharp text) or `canvas` (better for large datasets)

Custom Visual Registration (Required)

Copying a working Deneb visual with `pbir cp` carries its registration. For a new visual, inspect `publicCustomVisuals` with `pbir get` and update the complete list through `pbir set --json`, preserving any existing ids. Never edit `report.json` directly.

Workflow: Creating a Deneb Visual

Step 1: Add the Visual

Create the visual and bindings through `pbir`:

pbir add visual deneb7E15AEF80B9E4D4F8E12924291ECE89A \
  "Report.Report/Page.Page" --name RevenueByCategoryDeneb
pbir visuals bind "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" \
  --add "dataset:Sales.Category" --type Column
pbir visuals bind "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" \
  --add "dataset:Sales.Revenue" --type Measure

All fields bind to the single `dataset` role. Use `Table.Column` for columns and `Table.Measure` for measures. Field names in bindings must match those used in the Vega/Vega-Lite spec.

Step 2: Write the Spec

Create a Vega-Lite (or Vega) JSON spec file. Key difference:

• **Vega-Lite:** `"data": {"name": "dataset"}` (object)
• **Vega:** `"data": [{"name": "dataset"}]` (array)

{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": {"name": "dataset"},
  "mark": {"type": "bar", "tooltip": true},
  "encoding": {
    "y": {"field": "Category", "type": "nominal"},
    "x": {"field": "Value", "type": "quantitative"}
  }
}

See `examples/spec/` for complete spec files (Vega and Vega-Lite) and `examples/visual/` for full PBIR visual.json files. Field names in the spec must match the `nativeQueryRef` (display name) from the field bindings.

Step 3: Inject the Spec

pbir visuals deneb "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" \
  --spec-file chart.vl.json --provider vegaLite

The CLI handles PBIR encoding. Keep ordinary Vega or Vega-Lite JSON in the spec file.

Step 3b: Review

Before presenting the spec to the user, dispatch the `deneb-reviewer` agent to validate syntax and provide design feedback.

Step 4: Validate

pbir visuals bind "Report.Report/Page.Page/RevenueByCategoryDeneb.Visual" --show
pbir validate "Report.Report" --all

Spec Authoring Rules

Data Binding

• Vega: `"data": [{"name": "dataset"}]` (array form)
• Vega-Lite: `"data": {"name": "dataset"}` (object form)
• Fields reference display names. Special characters (`.`, `[`, `]`, `\`, `"`) become `_`
• Spaces are NOT replaced -- field names keep their spaces (e.g., `"Order Lines"`)

Field Name Escaping in Expressions (Critical)

Escaping depends on whether the spec is standalone or injected into a PBIR visual.json:

**Standalone spec files** (in `examples/spec/`): use double quotes with JSON escaping:

{"calculate": "datum[\"Order Lines\"] - datum[\"Order Lines (PY)\"]", "as": "diff"}

**Inside PBIR visual.json** (in `examples/visual/`): the entire spec is a single-quoted DAX literal string. Field names with spaces use doubled single quotes (`''`):

datum[''Order Lines''] - datum[''Order Lines (PY)'']

Single quotes that are NOT part of field name escaping (e.g., string literals in filter expressions like `datum.Series == 'Actuals'`) work as-is because they don't conflict with the outer single-quote wrapper.

Responsive Sizing (Vega)

Use Deneb's built-in signals for responsive container sizing:

"width": {"signal": "pbiContainerWidth - 25"},
"height": {"signal": "pbiContainerHeight - 27"}

The offsets account for padding. For absolute positioning of text marks, use `{"signal": "width"}` instead of hardcoded pixel values.

Config (Separate from Spec)

Always provide a config file for consistent styling. See the Standard Config section in `references/vega-patterns.md`. Key settings: `autosize: fit`, `view.stroke: transparent`, `font: Segoe UI`.

Theme Integration

Use Power BI theme colors instead of hardcoded hex values:

| Function/Scheme | Purpose | Usage in Vega | |-----------------|---------|---------------| | `pbiColor(index)` | Theme color by index (0-based) | `{"signal": "pbiColor(0)"}` | | `pbiColor(0, -0.3)` | Darken theme color by 30% | Shade: -1 (dark) to 1 (light) | | `pbiColor("negative")` | Sentiment colors | `"min"`, `"middle"`, `"max"`, `"negative"`, `"positive"` | | `pbiCo