pbi-report-design

Power BI レポートのデザイン

レポートを変更する場合は、必ず pbir を使用してください。 pbir-format スキルは、スキーマの参照専用です。 CLI を利用できない場合や、必要な操作が用意されていない場合は、作業を中止して不足している機能を報告してください。

Power BI レポートのデザインに関するベストプラクティスとガイドラインです。一般的で書式の整っていないレポート（「Power BI Slop」）を避けるため、これらのガイドラインに厳密に従ってください。

データビジュアライゼーションのルールとガイドラインを守りながら、革新性を発揮し、新たな可能性を追求してください。Power BI の制約の範囲内で、見た目や装飾よりもシンプルさと効果を重視してください。レポート、ページ、ビジュアルは、見た目の「美しさや立派さ」ではなく、特定の問いへの回答に焦点を当て、認知負荷を最小限に抑えてください。

ユーザーのリクエストがこれらのガイドラインに反する場合は、異議を唱え、より良い代替案を説明してください。目標は、より良い成果につながる選択肢をユーザーに伝えることです。

デザインのアイデンティティ（レイアウトの前に確定）

レイアウト作業に入る前に、レポートのアイデンティティを確定し、後のあらゆる選択の根拠とします。

1. トーンを1つ選ぶ……インクの使用量を restrained、corporate、editorial、technical のいずれかに決め、アクセントカラーの数、彩度、グリッド線の太さ、注釈の目立たせ方を固定します
2. シグネチャーを1つ選ぶ（多くても2つ）……ヘッダーバンド、単一のアクセントカラーによるルール、固定ナビゲーションレール、KPI のシルエット、コールアウトのスタイル、目標線の表現方法など、繰り返し使う要素を1つ選び、すべてのページで同じように使うことで、レポート全体に一貫性を持たせます
3. 各ページが答える問いに応じて、ページごとに形状を1つ割り当てます（summary、monitoring、exploration、comparison、narrative）

トーンとシグネチャーを一度記録することで、「色を抑える」という指針が全体に反映される決定事項になります。トーンの予算とシグネチャーの一覧については references/design-identity.md を、各ページへの形状の割り当てについては references/page-shapes.md を参照してください。アイデンティティは、ビジュアルごとのオーバーライドではなく、modifying-theme-json スキルを使ってテーマに反映してください。

基本ルール

1. 3-30-300 ルール： 最も重要で詳細度の低い情報は左上（KPI、カードなど）に、最も重要度が低く詳細度の高い情報は右下に配置します
2. タイトル： すべてのレポートページには、textBox の visualType を使用したタイトル、またはレポートページのキャンバスに追加した背景画像内のタイトルを設定します
3. ビジュアルの配置、整列、間隔： すべてのビジュアル間の間隔と、ページ端（余白）からの間隔を均等にします。ビジュアルの配置が揃っていない場合や、間隔が均等でない場合は、整列と間隔を均等にするよう修正します
4. テーマ： レポートでは、Power BI のデフォルトテーマとは異なるテーマを使用します。推奨テーマは sqlbi テーマです（テンプレートの適用方法については modifying-theme-json スキルを参照してください）。テーマを使うと、優れたデザインの実践やブランド、スタイルのガイドラインに沿った、すべてのグラフに共通するデフォルトのスタイルを設定できるため、テーマの使用を推奨します
5. セマンティックモデル： Power BI のレポートは複雑です。基盤となるセマンティックモデル（.SemanticModel フォルダー内にある「厚いレポート」または Power BI/Fabric で公開されたモデルである「薄いレポート」）に依存します。Power BI レポートの機能の多くは、セマンティックモデルの設計または DAX コードに由来します
6. レポート拡張機能、つまり薄いレポートのメジャー： Power BI レポート内で、「薄いレポートのメジャー」または「ビジュアル計算」と呼ばれる計算ロジックを作成できます。これらは控えめに使用し、「レポート固有」のシナリオに限って使用します
7. ビジュアルのフィールド： すべてのデータビジュアルにはフィールドのバインドが必要です。また、バインドするフィールドはすべてモデルに実在する必要があります。フィールドがバインドされていないビジュアルを配置する理由はありません
8. グラフの選択： 各シナリオで使用するビジュアルは適切に選択します。このスキルでは、ビジュアルの使い分けが不可欠です。
9. 色の使用： 色と書式の選択は、ビジュアルごとに決めるのではなく、確定したアイデンティティ（選択したトーンと特徴）に基づく必要があります。色はインラインの hex ではなく、テーマ（themedataColor）から取得します。これにより、アイデンティティが反映され、テーマを変更しても一貫性が保たれます。色は彩度を抑えたソフトなものにします。意味を暗示する色（赤＝悪い、緑＝良いなど）は、その意味を表すために使用する場合を除き、避けてください。色覚多様性に配慮し、アクセシブルなパレットを使用します（たとえば、赤と緑の組み合わせではなく青を使用します）。
10. 前注意的属性： スタイルや色は、装飾ではなく、注意を促し視線を誘導するために使用します。ビジュアルの書式設定は意図を持って行い、単なる見た目のために行わないでください。可能な限り、スタイルは個別のビジュアル設定ではなくテーマに保存します
11. フォント： Segoe UI と Segoe UI Semibold を推奨します。ユーザーのコンピューターでの表示が保証されないため、カスタムフォントは使用しないでください。ビジュアルとページのサイズを考慮し、フォントが読みやすい大きさであることを確認してください
12. ページの目的： 各ページは、回答する質問に基づいて、1 つの形式にのみ対応させます（references/page-shapes.md を参照）。2 つの質問に答えようとするページは、2 ページに分けます。

ページレイアウトのガイドライン

変更前にページサイズを確認する

ビジュアルを追加または再配置する前に、必ず実際のページ寸法を確認してください。 ページサイズが 1280x720 または 1920x1080 だと決めつけないでください。テンプレートや既存のレポートによって異なります。オブジェクトモデルはビジュアルがページの境界内に収まるかを検証するため、ページ寸法を把握せずに位置やサイズを設定するとエラーが発生します。まず、ページの page.json ファイルで width と height プロパティを確認するか、オブジェクトモデルの page.width と page.height を使って寸法を確認してください。オブジェクトモデルでビジュアルのサイズを変更する場合は、境界を超える中間状態を避けるため、x と y より先に width と height を設定します。

標準ページサイズ

• 幅： 1280px（デフォルト）
• 高さ： 720px（16:9 のアスペクト比）
• 代替サイズ：高解像度ディスプレイ向けの 1920x1080

ビジュアルの間隔

• ビジュアル間の最小間隔： 16px
• ページ端の余白： ページ端から24-32px
• 一貫した配置： グリッドベースの配置を使用します
• 均等な間隔は必須です： 隣接するビジュアル間（横方向・縦方向）の間隔はすべて同じ値にします。ページ端からの余白もすべて同じ値にします。配置を確実に揃えるため、（余白、間隔、ページ幅、ページ高さ）から算術的に位置を計算してください。ビジュアルの位置が揃っていなかったり、間隔が不均等だったりする場合は、すぐに修正してください。これはレポートで最も目立つ品質指標の1つです。

詳細度のグラデーション

「詳細度のグラデーション」に沿ってコンテンツを配置します。

+------------------+------------------+
|   KPIs/Cards     |   KPIs/Cards     |  <- Top: High-level, important
|   (Summary)      |   (Summary)      |
+------------------+------------------+
|                                     |
|   Charts/Trends                     |  <- Middle: Context, trends
|   (Analysis)                        |
|                                     |
+------------------+------------------+
|                                     |
|   Tables/Details                    |  <- Bottom: Detailed data
|   (Drill-down)                      |
|                                     |
+------------------+------------------+

ビジュアル数のガイドライン

• ページあたりのビジュアルの上限： 12-15（パフォーマンスへの影響）
• KPI／カードの上限： 上部に4-6個
• スライサーの上限： ページあたり3個（代わりにフィルターペインを使用します）

ページタイトル

すべてのページにタイトルを付けてください。pbir を使って作成します。

pbir add title "Report.Report/Page.Page" "Page Title" --width 500

タイトルの配置：

• 左上隅、ページ余白の内側
• 選択したフォントが切れないよう、十分な高さを確保します
• 幅：400-600px（またはページ幅から余白を差し引いた幅）

テーマのガイドライン

まずテーマを必ず確認する

ビジュアルの書式を変更する前に：

1. テーマのワイルドカードを確認します：visualStyles["*"]["*"]
2. ビジュアルタイプのオーバーライドを確認します：visualStyles.lineChart["*"]
3. 本当に個別対応が必要な場合に限り、visual.json でオーバーライドします

テーマとビジュアルを変更する場合

• あるタイプのすべてのビジュアルを変更する場合 → テーマ
• デザイン基準を設定する場合 → テーマ
• テーマのルールに対する単一のビジュアルの例外 → ビジュアル
• コンテンツ固有の強調表示（1つのコールアウト、1つの基準線） → ビジュアル

テーマカラーの使用

16進数コードよりテーマカラーを優先してください：

// Good - uses theme color
"expr": {"ThemeDataColor": {"ColorId": 1, "Percent": 0}}

// Avoid in visuals - use only in extension measures
"expr": {"Literal": {"Value": "'#118DFF'"}}

セマンティックカラー（拡張機能のメジャーから返される値）：

• "good" - 正の値（緑）
• "bad" - 負の値（赤）
• "neutral" - 中立／変化なし（灰色／黄色）
• "minColor" - グラデーションの最小値
• "maxColor" - グラデーションの最大値

アクセシビリティ（WCAG 2.1）

代替テキスト

すべてのビジュアルに、内容を説明する代替テキストを設定してください。

"visualContainerObjects": {
  "general": [{
    "properties": {
      "altText": {
        "expr": {"Literal": {"Value": "'Line chart showing monthly sales trend from January to December 2024'"}}
      }
    }
  }]
}

色のコントラスト

• 背景上のテキスト：コントラスト比を最低4.5:1にします
• 大きなテキスト（18pt以上）：コントラスト比を最低3:1にします
• 意味を伝える際に、色だけに頼らないでください

フォントサイズ

• 読みやすさの最低基準： 12pt
• グラフでの推奨値： 14pt
• タイトル： 16-24pt
• KPIの値： 24-48pt

影とモーション

• ドロップシャドウを最小限に抑えます（前庭障害への配慮）
• 可能な限りアニメーションを避けます
• テーマのワイルドカードで dropShadow.show: false を使用します

ビジュアルのベストプラクティス

カードと KPI

単独の数値には意味がありません。すべての KPI は、「良いのか悪いのか」（目標値と差分）、「良くなっているのか悪くなっているのか」（傾向）に答える必要があります。主なルールは次のとおりです。

• ページの上部または左側に配置し、1 ページあたり最大 5 個にします
• 目標値がある場合は、card よりも kpi ビジュアルタイプを優先します。指標、目標値、傾向線のデータロールが組み込まれています
• 必ず目標値と差分（絶対値とパーセンテージ）を含めます。目標値のメジャーが存在しない場合は、ユーザーに相談してください。セマンティックモデルに前年のメジャーを追加する（Tabular Editor CLI または tmdl スキルを使用）ことを提案するか、代替策として拡張メジャーを作成します。一般的な目標値には、前年（CALCULATE([Measure], DATEADD('Date'[Date], -1, YEAR))）、予算、移動平均があります
• 明確な目標値がない場合は、ユーザーに確認してください。KPI を単独の数値のままにしないでください。前期間、予算、カスタムしきい値のどれが適切か相談します
• 条件付き書式は主値ではなく、差分に適用します
• アクセシビリティのため、色と補助的な手がかり（矢印／アイコン）を組み合わせます
• サマリーレベルでは大まかに丸めます（「517,893,412」ではなく「518M」）
• 見栄えだけの指標より、意思決定につながる実用的な指標を選びます（「20% 変化テスト」を適用します。この数値が 20% 変化したら、誰かが異なる行動を取るべきでしょうか？）
• 自動生成される重複したサブタイトルは非表示にします
• インラインアイコンには SVG 拡張メジャーを使用します（custom-visuals プラグインの svg-visuals スキルを参照してください）

KPI の設計、目標値、傾向、書式の階層、アイコンの実装、アクセシブルなパレット、アンチパターンに関する詳しいガイダンスは、references/cards-and-kpis.md を参照してください。

グラフ

• 時系列データを除き、値の降順で並べ替えます
• グリッド線や軸の煩雑さを最小限に抑えます
• 重要度の低い要素には控えめな色を使います
• 重要なデータポイントは控えめに強調します

グラフタイプの選択（エンコーディングの階層、Cleveland-McGill ランキング）、データラベルの適切な使い方、スモールマルチプルに関するガイダンスは、references/chart-selection.md を参照してください。

LLM でよく見られる安易な既定値は避けてください。 KPI としてのゲージ、単色のカテゴリ別棒グラフ、並べ替えの欠落、カードだらけのレイアウト、生のフィールド名をタイトルに使うこと、インラインの HEX 値、グリッドからのずれ、二重の Y 軸、3D 表示、大きすぎる円グラフは、もっともらしく見えても読者の理解を妨げます。こうした案が求められた場合は、より良い選択肢を提示してください。references/anti-patterns.md を参照してください。

テーブルとマトリックス

テーブルには意図的な設計が必要です。「作成しやすい」ことと「読みやすい」ことは異なります。主なルールは次のとおりです。

• 詳細のドリルダウン用として下部に配置します（3-30-300 ルール）
• 意思決定を優先します。作成前に、問い、対象者、アクションを定義してください
• カテゴリ列 2 つ以上が階層を構成する場合（Key Account > Account > Product）は、tableEx よりも matrix を使用します
• 足すのではなく引きます。グリッド線や濃い縞模様を取り除き、余白で行を区切ります
• アルファベット順ではなく、最も重要なメジャー（多くの場合は差異）で並べ替えます
• 大きさをすばやく把握できるよう、主要メジャー列にデータバーを適用します
• カラースケールは差異列だけに適用します。すべてを書式設定すると、何も強調されなくなります
• 時系列の状況（「改善しているのか、低下しているのか」）が重要な場合は、スパークラインを追加します
• 完全な精度で表示します（表示単位は設定しません）。読者が詳細を確認するのはテーブルです

テーブルとマトリックスの選択、書式設定の考え方、条件付き書式の手法、スパークライン、階層設計、アンチパターンに関する詳しいガイダンスは、references/tables-and-matrices.md を参照してください。

スライサー

• 1 ページあたり最大 3 個にします
• 一貫した位置（上部または左側）に配置します
• 追加のフィルターにはフィルターペインを使用します
• ページ間でスライサーを同期することを検討します

フィルターペイン

フィルターペインには、色や装飾にとどまらない独自の情報設計があります。主な検討事項は、各フィルターカードをロックするか非表示にするか、モデルのフィールド名を変更せずにカードに名前を付ける方法、レポートレベルの設定（Apply ボタン、検索、allow-change-filter-type）です。references/filter-pane.md を参照してください。

モバイル

Power BI では、デスクトップページを縦向き画面用に自動で再配置しません。スマートフォン用レイアウトでは、手動で選んだ要素だけを狭いグリッドに再配置します。明示的に mobile.json で有効にしない限り、スマートフォンには何も表示されません。要素の選択モデルとファイルの仕組みについては、references/mobile.md を参照してください。

レポート評価基準

レポートの評価や監査を依頼された場合は、客観的な基準に焦点を当てます。主観的な評価は AI にとって困難です。レポートを直接「見る」ことはできず、美しさ、認知負荷、有効性を直感的に捉えることもできません。この制約をユーザーに強調してください。

客観的なチェックリスト

1. ページ数： 通常、5～8ページを超えると過剰です
2. 1ページあたりのビジュアル数： ビジュアルの数は目安であり、基準となるのはビジュアルごとのクエリコストです（references/layout-guidelines.md のパフォーマンスに関するセクションを参照）。テキストボックス、画像、図形、ボタンはクエリを発行しません。
3. テーマの使用： 一貫した書式設定のため、レポートではカスタムテーマを使用してください
4. レイアウトの一貫性：
   • ビジュアル間の間隔は均等ですか？
   • ページにタイトルはありますか？
   • 詳細度のグラデーション（重要な情報を左上に、詳細な情報を右下に）に沿っていますか？
   • カード／KPI は上部または左側に配置され、4～6個未満ですか？
   • スライサーは3個未満ですか（代わりにフィルターペインを使用してください）？
   • 更新日、リンク、コンテキストなど、役立つ要素はありますか？
5. 色の効果：
   • 条件付き書式は控えめに使用されていますか（情報過多を招いていませんか）？
   • 色は落ち着いた控えめなものですか（派手で鮮やかではありませんか）？
   • 赤やオレンジなど、否定的な印象を与える色は、否定的な値にのみ使われていますか？
6. 情報とインクの比率： 不要な要素は減らされていますか（グリッド線を薄くする、不要な軸やラベルを無効にするなど）？
7. 読みやすさ： すべての要素で十分なフォントサイズが使われていますか？
8. アクセシビリティ： 前庭への影響を避けるため、影は最小限に抑えられていますか？
9. フォントの一貫性： フォントサイズを絞り、すべてのデバイスで使えるシンプルで読みやすいフォントを使用していますか？
10. 並べ替え： 時系列などの理由がない限り、ビジュアルは降順に並べ替えられていますか？

評価結果

評価する際は、次の内容を提示してください。

• 問題点とその具体的な場所
• 重大度（重大、警告、提案）
• コマンドやパターンを含む推奨修正案

デザインの最終ゲート

デザインの完成を宣言する前に、references/quality-gate.md の最終ゲートを実行してください。これはビルド前の計画段階で実行するチェックリストではありません。完成した成果物を対象に、リリース可能かどうかを判断するものです。アイデンティティが全体に反映されていること、各ページに明確な意図が1つあること、間隔と余白が均等でグリッドに沿っていること、コールアウトがモデルの根拠に裏付けられていること、アクセシビリティの要件を満たしていることを検証します。エージェントはキャンバスを見られないため、このゲートと**pbir-cli** スキルのスクリーンショットレビューループを組み合わせてください。ページをレンダリングして確認し、JSON から推測した内容を検証します。

よくあるデザイン上の問題

問題：認知的過負荷

症状： 色、ビジュアル、データポイントが多すぎます

修正：

• ビジュアルの数を減らします
• 落ち着いたカラーパレットを使用します
• 詳細度のグラデーションを適用します
• 重要でない要素を非表示にします

問題：間隔の不統一

症状： 余白が不均等で、ビジュアルが揃っていません

修正：

• グリッドに基づいて配置します
• ビジュアルのサイズを標準化します
• 一貫した余白を適用します

問題：読みやすさの低さ

症状： フォントが小さく、コントラストが低いです

修正：

• フォントサイズを大きくします（最小12pt）
• 色のコントラスト比を確認します
• 適切なフォントの太さを使用します

参考資料

• references/design-identity.md -- コミットを起点とするアイデンティティ：トーンの予算（控えめ／コーポレート／エディトリアル／テクニカル）、シグネチャーのカタログ、テーマへのアイデンティティのシリアライズ
• references/page-shapes.md -- 意図（サマリー／モニタリング／探索／比較／ナラティブ）に応じて、各ページを1つの形状に割り当てます。何を含めるか、何を含めないか、レイアウトの簡潔さを解説します
• references/anti-patterns.md -- 避けるべき横断的なデフォルト設定（KPI としてのゲージ、単色の棒グラフ、並べ替えの欠如、カードの壁、生のタイトル、インラインの hex、グリッド外、二重軸、3D、過大な円グラフ）とその修正方法
• references/quality-gate.md -- デザインの品質ゲート：最終確認（アイデンティティの反映、ページごとに1つの意図、均等な間隔、根拠に基づくコールアウト、アクセシビリティ）を、問題／場所／重大度／修正の形式で示します
• references/cards-and-kpis.md -- KPI カードのデザイン：目標、差分、トレンド、書式の階層、アイコン、アクセシブルなパレット、アンチパターン、レビューチェックリスト
• references/tables-and-matrices.md -- テーブルとマトリックスのデザイン：意思決定のフレームワーク、「足すのではなく引く」という考え方、条件付き書式、並べ替え、スパークライン、マトリックスの階層、アンチパターン
• references/layout-guidelines.md -- キャンバスの寸法、間隔の段階（グループ内／グループ間／余白）、配置ルール、パフォーマンスのコストモデル
• references/visual-colors.md -- 色の原則、CF の方式選択（グラデーション／ルール／フィールドの値／アイコン）、セマンティックトークン、アクセシビリティ
• references/page-titles.md -- タイトルの実装、アクセシブルなタイトルの文言、非表示タイトル／代替テキストのルール
• references/chart-selection.md -- エンコーディングの階層（Cleveland-McGill の順位付け）、チャートタイプの選択、データラベルの適切な使用、小さな複数チャート
• references/tooltips-and-annotations.md -- レポートページのツールヒントのデザイン、使用を避ける場合、ガイド付き分析のための注釈プリミティブ
• references/filter-pane.md -- ロックと非表示の使い分け、カードの命名、カードの順序、適用済み／利用可能のスタイル、レポートレベルの設定
• references/mobile.md -- 厳選されたサブセットとしてのスマートフォンレイアウト、mobile.json の仕組み、含めるもの／除外するもの
• references/custom-visuals.md -- 自作と購入の優先順位、AppSource／組織ストアのトレードオフ、ライセンスの不足

関連スキル

レポートの構造と形式

• pbir-format（pbip プラグイン）-- visual.json、page.json、report.json の構造に関する PBIR JSON 形式のリファレンス
• pbip（pbip プラグイン）-- PBIP プロジェクトの構造、テーブル／メジャーの名前変更、プロジェクトのフォーク

カスタムビジュアル

Power BI が標準で提供するビジュアルだけでは不足する場合、レポートにはカスタムビジュアルが必要になることがよくあります。パッケージ化されたサードパーティ製ビジュアルを使う前に、必ずリポジトリ内のコードパスを検討してください。自作と購入の判断、および AppSource／組織ストアのトレードオフについては、references/custom-visuals.md を参照してください。

リポジトリ内のコードビジュアル向けスキルの選択（すべて custom-visuals プラグインに含まれています。claude plugin install custom-visuals@power-bi-agentic-development で追加してください）：

• deneb-visuals -- Vega／Vega-Lite の宣言型ビジュアル。高度なカスタムインタラクティブチャート（クロスフィルタリング、ツールヒント、ホバー）に推奨
• svg-visuals -- DAX メジャーによる SVG。行数上限の問題がない、テーブル／マトリックス／カード内のグラフィックに推奨
• python-visuals -- matplotlib／seaborn スクリプト（静的 PNG）。レンダリング時に計算する必要がある統計ビジュアライゼーション向け
• r-visuals -- ggplot2 スクリプト（静的 PNG）。forecast、pheatmap、corrplot など、R の統計エコシステムに Python の代替手段がない場合向け

セマンティックモデル

レポートの機能は、基盤となるセマンティックモデルに大きく依存します。メジャー、計算列、リレーションシップ、階層、行レベルのセキュリティなど、レポートの機能の大半はレポートではなくセマンティックモデルで定義されます。レポートを設計または変更する際は、モデルについて理解したり、変更したりする必要が頻繁にあります。主なスキルは次のとおりです。

• tmdl（pbip プラグイン） -- メジャー、列、リレーションシップを直接 TMDL ファイルで編集します
• te-docs（tabular-editor プラグイン） -- モデル操作用の Tabular Editor CLI
• c-sharp-scripting（tabular-editor プラグイン） -- モデルを一括変更する C# スクリプト
• bpa-rules（tabular-editor プラグイン） -- モデルの品質を確認する Best Practice Analyzer ルール
• connect-pbid（pbi-desktop プラグイン） -- Power BI Desktop のローカル Analysis Services インスタンスに接続し、モデルをリアルタイムでクエリおよび変更します