powerbi-report-design

Power BI 报表设计技能

此技能为 Power BI 报表提供设计指导。它确定设计风格（基调 + 标志性元素），将用户请求分配给每个页面适用的原型，并应用贯穿各处的设计原则（颜色、排版、图标、布局、交互性、无障碍性）。

范围界定 — 此技能决定报表应该是什么样子以及为什么。它不会编写 PBIR 文件。生成设计约定后，将任务交给 powerbi-report-authoring 处理所有文件操作：创建页面/视觉对象、注册主题、编码表达式、设置格式对象以及验证。

必须／优先／避免

必须

• 在做出设计决策之前，检查语义模型或可用字段。
• 给出具体的设计选择：基调、标志性元素、页面原型、图表选择依据、布局方向、颜色、排版和无障碍性考量。
• 将文件操作交给 powerbi-report-authoring；此技能不编辑 PBIR。

优先

• 仅针对会实质影响结果的缺失设计输入提问。
• 按需使用参考文件，而非加载完整设计目录。
• 如果设计将要实施，请输出结构化的 Design Brief:。

避免

• 不要直接创建页面、视觉对象、筛选器、主题或 PBIR 文件。
• 不要只给出“设计得现代一些”这类含糊指导，而不提供具体的布局、颜色和图表选择。
• 对于宽泛的创建/构建请求，不要取代规划工作流。

主题文件和示例

此根文件涵盖端到端工作流、主题、注意事项和设计约定模板。按需阅读主题文件：

文件	阅读时机
references/tone-catalog.md	当提示词未指定具体基调，或需要为后续步骤提供具体的调色板／字体选择时阅读
references/signatures.md	选择或优化报表的标志性视觉设计时阅读
references/archetype-composition.md	对于多页报表，如果页面角色或变体轮换尚不明确时阅读
references/archetypes/<name>.md	排版每个页面之前阅读 — 布局模板、信息密度、图表组合
references/chart-selection.md	选择图表类型之前阅读 — 编码层级、用途匹配
references/visual-cookbook.md	配置任何视觉对象之前阅读 — 各类型的排序、颜色、标签、条件格式
references/layout.md	在画布上放置视觉对象之前阅读 — 8 像素网格、构图模板
references/color.md	定义调色板、颜色语义、渐变或条件格式时阅读
references/typography.md	覆盖字体大小、字体搭配或字重惯例时阅读
assets/base.json	为生成的报表处理主题之前阅读 — 调整自定义主题时，保留其按文本框／卡片／表格类型设置的保护选项
references/interactivity.md	添加钻取、书签或交叉筛选规则时阅读
references/brownfield.md	重新设计、调整样式、更换主题或应用品牌时阅读
references/accessibility.md	最终确定任何报表之前阅读 — WCAG 检查清单、替代文本、对比度
references/anti-patterns.md	最终确定任何报表之前阅读 — 常见问题及修复方法
references/pre-flight-checklist.md	交接／最终审核前阅读完整检查清单
references/design-brief.md	交接之前阅读 — 完整的 Design Brief: 模板、机械化的 layout_contract 架构、页面标题／页眉区域、切片器位置、不重叠规则和验证清单

工作流

步骤 0 — 数据优先调查

在做出任何设计决策之前，检查语义模型。如果可用，请使用 Semantic Model MCP 服务，或直接读取 .tmdl 文件。对每个表抽取前 N 行样本，以了解分布、基数和数量级。整理表、列、度量值、层次结构和关系清单。将每个度量值与维度映射到它所回答的分析问题。

步骤 1 — 设计风格

在路由到图表类型或选择图表之前，先确定基调和标志性设计。基调决定报告的整体观感；标志性设计则是在各页面反复出现、定义整体视觉风格的设计元素。如果提示词没有指定具体风格，请使用 references/tone-catalog.md 和 references/signatures.md 来选择、混搭或设计基调与标志性设计。不要生搬硬套目录中的条目；关键是确定一种具体风格，让它指导配色、字体、布局和重复出现的视觉处理方式。对于棕地改版，请阅读 references/brownfield.md，并记录当前和目标基调与标志性设计。

步骤 2 — 页面类型路由

按页面路由，而不是按报告路由。即使是一个宽泛的请求（“制作一份涵盖我们业务所有方面的报告”），通常也可以拆分为面向不同受众、服务不同目的、更新频率各异的页面，因此需要采用不同的页面类型。将每个页面视为独立的路由决策。

信号	页面类型	参考资料
高管层、董事会、总经理；≤10 秒浏览；“进度是否符合计划？”	高管摘要	references/archetypes/executive-summary.md
轮班操作员、NOC、监控大屏；“是否出了故障？”	运营监控	references/archetypes/operational-monitor.md
分析师；检验假设；“X 为什么会发生？”	分析画布	references/archetypes/analytical-canvas.md
由作者主导论述；“事情是这样发生的”	叙事故事	references/archetypes/narrative-story.md
排名、基准比较、差异；“相较于什么？”	对比基准	references/archetypes/comparative-benchmark.md

信号含糊时，默认选择分析画布——这是最灵活的页面类型，也能在信息不足时妥善适配。

提示词含糊时：先询问，再路由。 如果缺少受众、目的、页面数量或筛选深度等信息，提示词就算含糊。遇到这种情况，请停下来，以面向用户的说法提供 2–3 个具体且有名称的选项（不要透露页面类型名称）。每个选项都应结合第 0 步中的语义模型，指定一种页面类型和变体。如果用户作出选择，就继续；如果仍不确定，再问一个用于缩小范围的问题；最多经过两轮后，选择最合适的选项，在 variant_rationale 中记录假设，然后继续。

然后选择布局变体。 每份页面类型参考文件都提供 2–3 种布局变体（A / B / C），并附有基于数据信号的选择表。根据第 0 步的数据形态，逐页查阅变体选择表。不要习惯性地默认选择变体 A。记录所选变体和促成该选择的数据信号（在 Design Brief: YAML 中填写 layout_variant 和 variant_rationale）。

将页面类型的区域视为参考建议，而非必选项。 布局变体只是布局起点，不是必须逐项满足的组件清单。每张卡片、重点提示、注释和背景信息块都必须通过回答一个独立的分析问题来证明其占用空间的价值。如果语义模型缺少所需的衍生洞见（差值、差异百分比、排名变化、异常阈值、比较基线或动态说明文字），就移除或改作他用，不要用重复的绝对值填充该区域。

对于多页面报告，请参阅 references/archetype-composition.md——其中介绍了常见组合（高管摘要 + 下钻、运营 + 详情、故事 + 证据、多领域）以及跨页面的变体轮换规则。避免整份报告都采用同一种页面类型；如果多个页面使用相同类型，而数据信号支持不同变体，就应轮换使用变体。

步骤 3 — 图表选择

阅读 references/chart-selection.md，为每个分析问题选择合适的可视化类型。遵循视觉编码层级：位置 → 长度 → 角度 → 面积 → 色相。先抽样查看数据——折线图上的线条平坦，或柱状图只有两根柱子，都可能说明选择了不合适的可视化方式。

步骤 4 — 可视化配置

阅读 references/visual-cookbook.md，了解各类可视化的规则：排序方式、配色策略、标签位置、坐标轴配置和条件格式。这些规则决定图表看起来专业还是业余。在画布上放置可视化之前，请先阅读 references/layout.md。

步骤 5 — 主题

根据步骤 1 确定的设计标识调整报表主题。对于生成的报表，请从 assets/base.json 开始，或在创建适配的自定义主题时保留其中关键的类型级防护设置：textbox 的内边距／背景／边框覆盖、cardVisual 的零内边距／卡片间距、表格自适应内容的样式、隐藏可视化标题，以及特定类型的图表默认值。不要用一刀切的通配符 visualStyles["*"]["*"].padding／背景替代这些设置，除非已检查并覆盖所有受影响的可视化类型。如果报表已有主题，除非用户要求更换主题或刷新品牌风格，否则应予以保留。有关主题注册的完整机制，包括调整 assets/base.json 时如何选择 $schema 版本，请使用 powerbi-report-authoring 技能。

步骤 6 — 规范设计契约

输出一个结构化的 Design Brief: YAML 块。它是与 powerbi-report-authoring 的契约。根据步骤 0–5 填写每个字段的具体值，并为每个页面提供机械化的 layout_contract。

在规划器工作流中使用此技能时，请将此 YAML 块嵌入 _brief/report-spec.md 的“Canonical design contract”部分。完整模板、字段说明、现有项目的当前／目标字段、最简简报应急方案、页面级机械化架构、示例和验证清单，请阅读 references/design-brief.md。

该契约必须包含设计来源标记（generated_by: powerbi-report-design）和 contract_version。全新报表默认采用 FHD（1920 x 1080），除非用户要求其他尺寸；现有报表应保留画布尺寸，除非已获准调整大小。在交接复杂页面之前，必须确保其 layout_contract 包含 page_title 的位置、预留的页眉／切片器区域或有充分理由的筛选器栏、space_audit，以及互不重叠的区域／位置。

请记住以下最简结构；完整模板和验证规则请参阅 references/design-brief.md：

Design Brief:
  generated_by: powerbi-report-design
  contract_version: 1
  mode: greenfield
  design_identity: { tone: <tone>, signature: <signature> }
  pages:
    - name: <descriptive insight title>
      role: <landing | detail | drillthrough | tooltip>
      archetype: <Executive | Analytical | Operational | Narrative | Comparative>
      layout_variant: <A | B | C>
      variant_rationale: <one sentence: which data signal drove this pick>
      layout_contract:
        canvas: { width: 1920, height: 1080, margin: 32, gutter: 24, snap: 8 }
        grid:
          columns: 12
          rows: 12
          regions:
            header:  [1, 1, 9, 2]
            filters: [9, 1, 13, 2]
            body:    [1, 2, 13, 13]
        placements:
          - id: page_title
            region: header
            kind: textbox
            text: <descriptive insight title>
          - id: <visual_or_slicer_id>
            region: <defined region>
            kind: <cardVisual | barChart | lineChart | tableEx | slicer | azureMap | ...>
            purpose: <one analytical question>
            field_bindings: <Table[Field] or role map>
        space_audit:
          content_cell_count: <cells after excluding reserved header/slicer/rail>
          placed_cell_count: <cells covered by regions with placements>
          empty_cell_pct: <0-100>
          unplaced_regions: []
          largest_region: { name: <region>, pct_of_content: <0-100> }
          balance_rationale: <why region sizes match analytical priorities>

最简简报应急方案（适用于简单的单可视化需求）：只需 3 行—— mode、design_identity { tone, signature }（现有项目可写为 unchanged），以及一个决策。示例请参阅 references/design-brief.md。

步骤 7 — 审查与交接

交接之前，请阅读 references/design-brief.md 和 references/pre-flight-checklist.md，然后对照两者严格审查设计契约。对于现有项目，还要逐项检查 references/brownfield.md 中针对现有项目的内容。交接前修复所有问题。

如果可以获得独立审查（另行推理审查或由同事审查），请进行审查——布局缺口、缺失的切片器、单色图表、原始字段名以及主题未传递等问题，最容易由不同的人发现。

契约通过清单检查后，交由 powerbi-report-authoring 实施。

常见问题

这些不明显的问题会导致报告看起来异常或缺乏差异。请逐项检查。

声明了基调却从未贯彻 — 简报写着 tone: editorial newsroom，但最终采用的字体、配色和网格线／边框样式与其他所有报告完全相同。基调必须体现在具体的视觉选择中。查看基调目录行中的下游选择列。

页面背景 — 每个页面都要使用有意设计的页面底色；避免白色画布搭配白色视觉容器，否则视觉效果会显得平淡、没有边框，并融入背景。具体的 page.json 实现由制作环节负责。

避免重叠／控件被裁切 — 除非明确有意重叠（例如，图表后方的注释形状），否则视觉对象的边界框不得重叠。顶部栏切片器应位于预留的标题／切片器区域：页面标题保持在左侧锚点位置，切片器放在右侧。图表／卡片应从该区域下方开始，不能位于其下方。提高切片器的 z-order 不能替代避免布局重叠。

重复的说明卡 — 与相邻图表中已显示的绝对值重复的侧边说明卡或 KPI 上下文卡片只会造成干扰。说明卡需要将 insight_basis / callout_value_basis 与派生比较、阈值、排名、异常或生成的叙述相关联；否则请移除说明卡，将空间留给能补充信息的图表、表格、筛选器上下文或注释。

时间切片器粒度 — 不要仅仅因为存在日期列，就想当然地选择完整日期范围的 Between 切片器。对于高管页面和按年粒度的数据，请使用年份下拉菜单／平铺切片器，除非用户需要按日／月范围探索，且该列是可渲染的 Date/DateTime 字段。

文本框滚动条 — 文本框需要足够的高度来容纳字号以及 VCO／主题内边距，否则 Desktop 会显示滚动条。高度公式：max(18, ⌈fontSize × 25/16⌉) + padding_top + padding_bottom。如果主题使用通配符内边距，请添加文本框专用的零内边距覆盖设置，或增加文本框高度。

颜色映射规范 — 每个绑定度量值的视觉对象都必须遵循 Design Brief.color_map。measure_match 表示在卡片、线条、条形、地图和表格中精确重用基础颜色；gradient 表示同一度量值从色调渐变至基础颜色。交付前请审查已制作的报告，检查是否存在不匹配。

单色条形 — 单度量值条形图可能将所有条形渲染为同一颜色，因为 PBI 按系列而非类别分配调色板颜色。如果类别间对比很重要，请在简报中指定所需的逐类别配色或渐变处理，并由制作环节处理具体实现。不要通过将同一字段同时复制为类别和图例来绕过这一点。

原始字段名 — Agent 一再将 method_category、customer_id、Count of order_line_id 或 date_of_enrolment 等原始数据库名称留在坐标轴、标题和图例中。请检查每个坐标轴标签、列标题、图例条目和卡片标签。为每个字段设置易于理解的显示名称。

聚合的显示名称 — 使用“总战斗数”或“学生人数”等描述性名称，而不是“fight_key 的总和”或“student_id 的计数”。通过投影中的 displayName 或坐标轴标题覆盖设置。

百分比格式 — 以小数存储的比率（例如，0.53）应显示为“53%”，而不是“0.53”。请在相关视觉对象属性中将数字格式字符串设为 "0%" 或 "0.0%"。