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 px グリッド、構成テンプレート
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 — アーキタイプの振り分け

レポート単位ではなく、ページごとに振り分けます。「事業全体を網羅したレポート」のような幅広い依頼でも、通常は対象者、目的、更新頻度が異なるページに分解され、それぞれ異なるアーキタイプが必要になります。各ページを個別の振り分け判断として扱ってください。

手がかり	アーキタイプ	参照先
C-suite、取締役会、GM。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 のセマンティックモデルに合わせた、特定のアーキタイプとバリアントの組み合わせを指定します。ユーザーが選択したら先に進み、まだ迷っている場合は、選択肢を絞るための追加質問を 1 つします。最大 2 回のやり取りの後、最適な選択肢を選び、その前提を 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 を読み、各分析上の問いに適したビジュアルタイプを選びます。エンコーディングの優先順位（位置 → 長さ → 角度 → 面積 → 色相）を守ってください。まずデータをサンプリングします。線がほぼ平坦な折れ線チャートや、棒が 2 本しかない棒グラフは、ビジュアルの選択が適切でないことを示しています。

Step 4 — ビジュアルの設定

ビジュアルの種類ごとのルール（並べ替え順、色の方針、ラベルの配置、軸の設定、条件付き書式）については、references/visual-cookbook.md を読んでください。これらのルールによって、グラフがプロフェッショナルに見えるか、素人っぽく見えるかが決まります。キャンバスにビジュアルを配置する前に、references/layout.md を読んでください。

Step 5 — テーマ

Step 1 で決めたデザインアイデンティティに合わせて、レポートのテーマを調整してください。生成するレポートでは、 assets/base.json をベースにするか、カスタムテーマを調整して作成する際に、重要な種類別の保護設定を維持してください。対象となるのは、textbox のパディング／背景／境界線の上書き、cardVisual のパディング 0／カード間隔、テーブルの内容に合わせた拡大スタイル、非表示のビジュアルヘッダー、種類別のグラフ既定値です。影響を受けるすべてのビジュアルの種類を確認して上書きしない限り、これらを大まかなワイルドカード visualStyles["*"]["*"].padding ／背景で置き換えないでください。レポートにすでにテーマがある場合は、ユーザーがテーマの変更またはブランドの刷新を求めていない限り、そのテーマを維持してください。テーマ登録の詳細な仕組み（assets/base.json を調整する際の $schema のバージョン選択を含む）については、powerbi-report-authoring スキルを参照してください。

Step 6 — 正式なデザイン契約

構造化された Design Brief: YAML ブロックを出力してください。これは powerbi-report-authoring との契約です。Step 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>

最小限のブリーフを使う場合の例外（単純な単一ビジュアルの依頼）：mode、design_identity { tone, signature }（またはブラウンフィールドの場合は unchanged）、および 1 つの決定事項の 3 行で十分です。例については、references/design-brief.md を参照してください。

Step 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 フィールドでない限り、Year のドロップダウンまたはタイルを使用してください。

テキストボックスのスクロールバー — テキストボックスの高さは、フォントサイズに VCO／テーマのパディングを加えた分を確保してください。足りないと Desktop でスクロールバーが表示されます。高さの計算式：max(18, ⌈fontSize × 25/16⌉) + padding_top + padding_bottom。テーマでワイルドカードのパディングを使っている場合は、テキストボックス専用のパディングをゼロにするオーバーライドを追加するか、テキストボックスの高さを増やしてください。

カラーマップの規約 — メジャーに紐づくすべてのビジュアルは Design Brief.color_map に従う必要があります。measure_match は、カード、線、棒、マップ、テーブル全体で同じベースカラーを正確に再利用することを意味します。gradient は、同じメジャーに対して色を薄くした色からベースカラーへ変化させることを意味します。引き渡し前に、作成したレポートを監査し、色の不一致がないか確認してください。

単色の棒 — PBI はカテゴリではなく系列ごとにパレットカラーを割り当てるため、単一メジャーの棒グラフではすべての棒が同じ色で表示されることがあります。カテゴリごとのコントラストが重要な場合は、ブリーフでカテゴリ別またはグラデーションの扱いを指定し、具体的な設定はオーサリング側に任せてください。同じフィールドをカテゴリと凡例の両方として複製する方法で回避しないでください。

生のフィールド名 — エージェントは、method_category、customer_id、Count of order_line_id、date_of_enrolment などの生のデータベース名を、軸、ヘッダー、凡例にそのまま残しがちです。すべての軸ラベル、列ヘッダー、凡例項目、カードラベルを確認してください。すべてのフィールドに、人が読みやすい表示名を設定してください。

集計の表示名 — "Sum of fight_key" や "Count of student_id" ではなく、"Total Fights" や "Students" のような説明的な名前を使用してください。投影の displayName または軸タイトルのオーバーライドで設定してください。

パーセンテージの書式設定 — 小数（例：0.53）として保存されている率は、"0.53" ではなく "53%" と表示してください。該当するビジュアルのプロパティで、数値書式文字列に "0%" または "0.0%" を設定してください。