report-design

name	report-design
description	Use when designing report layout, page structure, visual selection, storytelling, and UX interactions. Triggers: "design report", "report layout", "page design", "visual selection", "report blueprint", "KPI card placement", "slicer layout", "storytelling", "information architecture", "design system tokens", "chart type selection".
user-invocable	true

Skill: Report Design (Layout, UX, Navigation)

Purpose

Design the Power BI report experience (pages, layout, visuals, interactions, navigation) based on:

• the functional specification (<ProjectName>/spec/*.md), and
• the finalized semantic model (<ProjectName>/PBIP/<ProjectName>.SemanticModel/definition/).
• any user-validated visual baseline, such as screenshots, manually refined report pages, or design feedback captured during the workflow.
• optional UI mockups or prototypes from Figma, React, screenshots, or other design tools.

All user-provided mockups, screenshots, PDFs, exports, and similar external design artifacts must be archived under <ProjectName>/spec/ before this skill uses them as input.

This step produces a design blueprint only. It does NOT implement PBIP report artifacts.

When visual mockups are provided, this step must first translate them into Power BI-feasible implementation strategies before finalizing the layout.

This step must convert requirements into a report that is:

• analytically clear,
• visually consistent,
• narratively intentional, and
• implementation-ready for Step 09.

Context Window Management (CRITICAL)

• Load only the minimum needed inputs for this step: the spec + the semantic model object names.
• Use references/report-design-visualization-best-practices.md for chart choice, storytelling flow, sorting logic, container styling, cross-filtering, accessibility.
• Use references/layout-guidelines.md for page dimensions, spacing, grid alignment, visual zones.
• Use references/cards-and-kpis.md for KPI card design, target sourcing, display units, gap formatting.
• Use references/tables-and-matrices.md for table/matrix formatting, conditional formatting, sparklines.
• Use references/visual-colors.md for color strategy, semantic colors, contrast, accessibility.
• Use references/mockup-to-powerbi-patterns.md when visual evidence such as Figma, screenshots, or React prototypes is provided.
• Use references/page-titles.md for title textbox implementation, paragraph structure.
• NEVER invent measure/field names: always read them from TMDL.
• If the user has manually refined one or more pages in Power BI Desktop, treat that validated visual grammar as authoritative unless it conflicts with the specification.

Input / Output

Input	Functional spec (<ProjectName>/spec/*.md), all TMDL files (visual field registry), optional user-validated visual baseline
Output	<ProjectName>/spec/report_blueprint.json

Prerequisites — MANDATORY

Before starting report design:

1. ✅ The semantic model exists and is valid (Steps 3–7 completed).
2. ✅ The specification describes report goals (audience, questions, KPIs, navigation expectations). If missing, ask targeted questions and STOP.
3. ✅ Model introspection is possible by reading TMDL files.
4. ✅ Any user-approved visual conventions discovered during the workflow are captured as design constraints for this step.

Official Reference: When designing pages and visual layouts, refer to the Microsoft official PBIR documentation for valid properties and schema constraints: https://learn.microsoft.com/en-us/power-bi/developer/projects/projects-report

Step 8 Procedure

8.1 Inputs to Read

1. Functional spec: <ProjectName>/spec/<spec>.md
2. Semantic model TMDL:
   • <ProjectName>/PBIP/<ProjectName>.SemanticModel/definition/model.tmdl
   • <ProjectName>/PBIP/<ProjectName>.SemanticModel/definition/tables/*.tmdl
   • <ProjectName>/PBIP/<ProjectName>.SemanticModel/definition/relationships.tmdl
3. Workflow evidence from previous approved steps, if relevant:

• <ProjectName>/workflow_state.json
• Step 07 test outputs

4. User-provided design evidence, if available:

• archived screenshots in <ProjectName>/spec/
• archived mockups, PDFs, or exports in <ProjectName>/spec/
• manual page reconstructions in Power BI Desktop
• explicit UX feedback captured in workflow state or project artifacts

5. Theme baseline, if visual evidence exists:

• current report theme JSON if already present
• brand palette, typography, spacing, container treatment, and semantic color cues extracted from the mockup

8.2 Build a Visual Design Field Registry (MANDATORY)

Create an internal registry of report-usable objects by reading TMDL (same anti-hallucination principle as Step 7):

• Measures: from _Measures.tmdl (exact display names)
• Date table: confirm the Date table and main Date column
• Dimensions: user-facing attributes (prefer non-hidden descriptive columns)
• Facts: avoid exposing technical keys; prefer measures
• Field parameters: detect disconnected calculated tables that expose dynamic-switch semantics and record their visible column, hidden metadata column, and allowed target fields

CRITICAL RULES:

• NEVER guess object names.
• If the spec uses business labels that don't map 1:1 to model objects, ask clarifying questions and STOP.

8.2A Mockup-to-PowerBI Translation Pass (MANDATORY when visual evidence exists)

If the user or orchestrator provides a mockup, screenshot, Figma export, or React-based visual prototype, perform a translation and feasibility pass before finalizing the storyboard or page layout.

For every relevant mockup component, classify implementation using this decision order:

1. native — realizable with a single native Power BI visual.
2. composite-native — realizable with multiple coordinated native visuals.
3. svg — realizable with inline SVG via DAX or extension measures.
4. deneb — realizable with Deneb custom visual.
5. approximation — not exactly reproducible, but can be redesigned credibly within Power BI constraints.
6. not-feasible — should be declared explicitly, not faked.

For each component, capture:

1. intended UX purpose;
2. chosen implementation mode;
3. Power BI constraints that affect fidelity;
4. workaround strategy if exact parity is impossible;
5. fidelity risk (low, medium, high).

Power BI constraint reminders:

1. Power BI is not a generic web layout engine.
2. Pixel-perfect replication of React/Figma components is not always realistic.
3. Interactions may need reinterpretation via slicers, bookmarks, tooltips, drillthrough, or page navigation.
4. Typography, spacing, and container composition should prioritize perceptual fidelity, not literal HTML/CSS parity.

8.2B Theme-First Translation Rule (MANDATORY when mockup exists)

If visual evidence exists, extract the visual design system before final page composition.

At minimum capture:

1. background and surface colors;
2. primary accent colors;
3. positive/negative/neutral sentiment colors;
4. typography hierarchy;
5. container styling (border, shadow, corner treatment, padding);
6. spacing rhythm for header, KPI zones, chart zones, and navigation.

These tokens must be reflected in the blueprint sourceDesign and designSystem sections and should be treated as the preferred input for theme-customization before large-scale PBIR implementation.

8.3 Build the Storyboard Before the Layout (MANDATORY)

Before placing any visual on a page, define the narrative skeleton for each page:

• Audience: who consumes the page
• Business question: what question the page answers
• Key takeaway: the one message the user should retain
• Evidence flow: KPI summary -> supporting trend/comparison -> detail/ranking
• Expected action: what decision or follow-up the page should support

Each page in the blueprint must answer a specific business question. A page without a clear question or takeaway is invalid.

Default storytelling flow:

1. Controls first: slicers and navigation
2. Hero insight second: top KPI band
3. Explanatory evidence third: trends, comparisons, relationships
4. Detail last: ranked tables or drill paths

8.4 Define a Page-Level Design System (MANDATORY)

Before generating page visuals, define reusable design tokens and layout rules that Step 09 can implement consistently.

The design system must include:

• Grid discipline: use an 8 px grid or consistent multiples of it
• Whitespace policy:
  • minimum gap between sibling visuals: 16 px
  • recommended gap between visual sections: 24 px
  • page edge breathing space: 16 px minimum
• Container separation: visuals must be visually distinct from the canvas using elevated cards, shadowing, border contrast, or another explicit container treatment
• Alignment policy: slicers aligned on a common row, KPI containers aligned on a common baseline, analytic visuals aligned by section
• Visual hierarchy: top-left and top band reserved for the highest-value information
• Title policy: action-oriented, unambiguous titles that state measure + comparison/breakdown
• Sorting policy: all charts and tables must have explicit sorting logic

Mandatory design decisions

Slicers

• Place primary slicers on a dedicated top row whenever space allows.
• Use consistent width, height, alignment, and container treatment.
• Prefer dropdown slicers for dense categorical filters.
• If a slicer controls a field parameter, treat it as an interaction control rather than a business filter and map its downstream target roles explicitly in the blueprint.
• If a slicer controls a measure parameter, explicitly constrain the companion dimensions used in the visual to ones that remain meaningful for every selectable measure.

KPI presentation

• Use a single card when one metric is the dominant headline insight.
• Use a multi-row card when the requirement is to show multiple heterogeneous KPIs in the same narrative band and equal emphasis is acceptable.
• Use separated KPI cards only when each KPI needs standalone emphasis, distinct thresholds, or clearly different semantic meaning.

Tables

• Tables must serve a specific detail or ranking purpose.
• Every table must define:
  • primary KPI used for sorting,
  • sort direction,
  • reason for the ordering.
• Default sort for leaderboard/ranking tables is descending by the primary KPI.
• Use ascending sort only when the business question explicitly targets low performers, earliest values, or another exception.

Chart clutter

• Remove non-essential labels, borders, legends, and gridlines when they do not add meaning.
• Prefer tooltips for secondary details instead of overcrowding the canvas.

8.5 Derive Report Information Architecture

From the spec and storyboard, define:

• Primary KPIs (what must be seen immediately)
• Supporting analysis (trends, comparisons, drivers, relationships)
• Detail and ranking content
• Tertiary controls (slicers, navigation, bookmarks, drillthrough)

Default to the simplest structure that satisfies the spec:

• If the spec is summary-only → single-page layout.
• If the spec includes drill-down needs → summary page + detail page.

Default page grammar:

• top filter band
• KPI band
• explanatory chart zone
• detail/ranking zone

8.6 Produce the Report Design Blueprint (OUTPUT)

The agent MUST generate and save the report design blueprint as a physical JSON file at <ProjectName>/spec/report_blueprint.json. This file will be the input for Step 9 (Report Implementation). Only AFTER saving the file, the agent must present a summary and stop for approval.

JSON Schema for report_blueprint.json

{
  "$schema": "report_blueprint_schema",
  "projectName": "<ProjectName>",
  "generatedDate": "<ISO 8601 timestamp>",
  "semanticModelPath": "<ProjectName>/PBIP/<ProjectName>.SemanticModel/definition/",
  "storytelling": {
    "narrativePattern": "callToActionLoop",
    "audienceNotes": [],
    "globalDesignConstraints": []
  },
  "sourceDesign": {
    "hasMockup": false,
    "mockupType": null,
    "fidelityGoal": "medium",
    "notes": []
  },
  "designSystem": {
    "gridUnit": 8,
    "pagePadding": 16,
    "visualGap": 16,
    "sectionGap": 24,
    "containerStyle": {
      "mode": "elevated",
      "shadow": true,
      "border": false
    },
    "slicerStyle": {
      "placement": "top-row",
      "container": "elevated",
      "alignment": "consistent"
    },
    "kpiStyle": {
      "preferMultiRowCardForGroupedHeterogeneousKpis": true,
      "singleCardReservedForHeroMetric": true
    },
    "tableStyle": {
      "requireExplicitSort": true,
      "defaultRankingDirection": "descending"
    }
  },
  "pages": [
    {
      "pageId": "Page1",
      "pageName": "Overview",
      "displayName": "Sales Overview",
      "goal": "Provide a summary of key sales KPIs and trends",
      "targetAudience": "Sales Manager",
      "storyCard": {
        "businessQuestion": "Are we on track against budget and where should the manager investigate first?",
        "keyMessage": "Budget variance is negative while FYTD sales remain concentrated in a subset of areas.",
        "expectedAction": "Inspect area-level variance and profitability drivers."
      },
      "width": 1280,
      "height": 720,
      "displayOption": "FitToWidth",
      "slicers": [
        {
          "field": "Dim_Date[FiscalYear]",
          "type": "dropdown",
          "label": "Fiscal Year",
          "containerStyle": "elevated",
          "position": {
            "x": 16,
            "y": 16,
            "width": 180,
            "height": 64
          }
        }
      ],
      "visuals": [
        {
          "visualId": "visual_01",
          "visualType": "multiRowCard",
          "mockupComponentName": null,
          "mockupIntent": null,
          "implementationStrategy": {
            "mode": "native",
            "primaryVisualType": "multiRowCard",
            "secondaryVisualTypes": [],
            "fallbackMode": null,
            "fidelityRisk": "low",
            "constraints": [],
            "workarounds": [],
            "notFeasibleAspects": []
          },
          "title": "Total Sales FYTD",
          "measures": ["Sales Amount FYTD"],
          "axisFields": [],
          "legendField": null,
          "narrativeRole": "hero-kpi",
          "containerStyle": "elevated",
          "sortBy": null,
          "defaultGranularity": null,
          "tooltip": null,
          "drillthrough": null,
          "position": {
            "x": 16,
            "y": 96,
            "width": 200,
            "height": 100
          }
        }
      ],
      "interactions": {
        "crossFilterMode": "highlight",
        "customInteractions": []
      }
    }
  ],
  "navigation": {
    "model": "tabs",
    "drillthroughPages": [],
    "bookmarks": []
  },
  "accessibility": {
    "altTextRequired": true,
    "colorBlindSafe": true,
    "notes": []
  },
  "performanceGuardrails": {
    "maxVisualsPerPage": 8,
    "avoidHighCardinalitySlicers": true,
    "preferMeasuresOverImplicitAggregations": true,
    "notes": []
  }
}

Blueprint Generation Rules

The agent MUST follow these rules when generating the JSON:

1. Page definitions: One object per page. pageId must be a valid folder name (e.g., Page1, Page2).
2. Visual definitions: Each visual must reference measures and fields that exist in the Visual Design Field Registry (8.2).
3. Field references: Use exact Table[Column] or [Measure Name] syntax as found in TMDL.
4. Positions: Provide approximate x, y, width, height values for visual layout (based on 1280x720 canvas) and keep consistent spacing.
5. No invented content: Every page, visual, and field must trace back to the functional specification.
6. Slicer definitions: Include all required filters/slicers with their source fields.
7. Field parameter definitions: If dynamic switching is required, represent it explicitly in the blueprint with the parameter table, visible parameter column, target visual(s), target role(s), and optional default selection.
8. Context compatibility: If a measure parameter is used, declare the allowed context dimensions for the visual and reject dimension choices that are not consistently related to every selectable measure through the active model relationships.
9. Narrative metadata: Every page must define the business question, key message, and expected action.
10. Container treatment: Every slicer, KPI band, and analysis visual must declare a container style or explicitly opt out with a reason.
11. Sorting metadata: Every sortable chart or table must define sortBy, including field and direction.
12. KPI grouping rationale: If a page shows multiple KPIs in one zone, choose between card and multiRowCard explicitly and record the reason.
13. Mockup translation metadata: If visual evidence exists, each mockup-driven visual must declare implementationStrategy and any relevant Power BI constraints or approximations.
14. No silent feasibility downgrade: If the chosen strategy is approximation or not-feasible, record it explicitly in the blueprint instead of hiding the limitation in narrative text only.

Recommended blueprint extension for field parameters:

{
  "visualId": "visual_02",
  "visualType": "tableEx",
  "fieldParameterBindings": [
    {
      "parameterTable": "Measure",
      "parameterColumn": "Measure",
      "targetRole": "Values",
      "defaultSelection": "Sales Amount FYTD",
      "allowedContextDimensions": ["Dim_Area[AreaName]"]