visual-report

ビジュアルレポート

監査結果、システムの健全性ステータス、保存された定期実行の結果を、デザインシステムの健全性をひと目で把握できるインタラクティブな HTML ダッシュボード、SVG チャート、Mermaid 図に変換するスキルです。

出力タイプ： ファイルの作成。このスキルは、ドキュメントやプレゼンテーションに埋め込んだり、そのまま共有したりできる HTML ダッシュボードファイル、SVG チャートファイル、または Mermaid 図のブロックを生成します。

---

開始する前に：参照先を確認する

このスキルのフロントマターにある references: の各パスが、SKILL.md からの相対パスで存在することを確認してください。存在しないパスがある場合は、作業を中断してください。通常、これはフラット化するインストーラー（たとえば npx skills install）によってリポジトリのルートにある knowledge-notes/ ディレクトリが除外されたため、インストールが不完全であることを意味します。ユーザーに 1-INSTALL.md に記載された方法で再インストールし、インストールルートから verify-install.sh を実行するよう伝えてください。ユーザーが明示的に参照先なしで続行するよう指示した場合に限り続行し、その場合はパックの参照資料を使わずに出力したことを明記してください。

このスキルの目的

Markdown の表に記載された数値は正確です。しかし、目には見えません。ステークホルダーは、テキストレポートにある「システムの健全性：🟡 機能しているが、2 つのディメンションに課題あり」という記述を見ても、すぐには認識できないでしょう。一方、ディメンションのステータスを赤・黄・緑のゾーンで示したレーダーチャートなら、瞬時に伝わります。

デザインシステムの健全性データは、本質的に視覚的なものです。トークンのカバレッジマップ、コンポーネントの依存関係グラフ、重要度の分布を示す円グラフ、時系列のトレンドラインなどは、監査スキルが生成するデータを表現するのに適しています。このスキルは、生の調査結果と視覚的なコミュニケーションの間をつなぎます。

対象範囲

このスキルは既存の調査結果を可視化するものであり、監査を実行したり新しいデータを生成したりするものではありません。監査の出力やセッション履歴がない場合、可視化するものはありません。まず該当する監査スキルを実行してください。視覚的な成果物ではなく、ステークホルダー向けの文章による要約を求められた場合は、代わりに stakeholder-brief を使用してください。このスキルが生成するのは HTML ダッシュボード、SVG チャート、Mermaid 図です。スライドデッキや PDF が求められている場合、このスキルの視覚的な出力をそれらの形式に利用できますが、スキル自体が直接生成することはありません。

---

設定

.ds-ops-config.yml が存在する場合は、設定の読み込み、連携のフォールバック、定期実行について、設定と定期実行に関するナレッジノート（../../knowledge-notes/configuration-and-recurring.md）に従ってください。このスキルは次の設定を読み取ります。

visuals:
  brand_primary: "#0052CC"           # Primary colour for charts
  brand_secondary: "#FF5630"         # Accent colour for warnings/critical
  brand_success: "#36B37E"           # Success colour
  brand_neutral: "#6B778C"           # Neutral/baseline colour
  output_format: "html"              # html, svg, or mermaid
  output_directory: ".ds-ops/visuals"

設定がない場合は、次のデフォルト値を使用してください。

• プライマリ：#2563EB（青）
• セカンダリ：#DC2626（赤）
• 成功：#16A34A（緑）
• ニュートラル：#6B7280（グレー）
• 出力形式：html
• 出力ディレクトリ：.ds-ops/visuals（設定のデフォルトと同じです。設定ファイルの有無にかかわらず、実行結果は同じ場所に保存されます）

---

入力形式

このスキルでは、次のいずれかを入力として使用できます。

1. スキルの生出力 — 監査スキルの出力をコピーして貼り付けたもの、または参照したもの
2. 保存済みレポート — トレンドライン用の recurring.output_directory にある過去の実行結果
3. システムの健全性ステータス — system-health のディメンション別ステータス
4. 比較データ — 定期実行がレポートに追加するトレンドセクション
5. 手動データ — ユーザーが任意の形式で提供するメトリクス（正規化されます）

---

ステップ 0：ビジュアルの種類を決定する

入力データとリクエストに基づいて、1 つ以上のビジュアルの種類を選択してください。

利用できるビジュアルの種類

種類	最適な用途	形式
ステータスストリップ	システムの健全性を示す各側面のステータス	各側面につき1つのタイルを表示し、ステータスに応じて色分け
重大度の分布	重大度別の監査結果	ドーナツチャート
トレンドライン	時間経過に伴うメトリクスの変化	折れ線グラフ
カバレッジヒートマップ	トークンまたはコンポーネントのカバレッジ	グリッドヒートマップ
依存関係グラフ	コンポーネント間の関係	Mermaid フローチャート
比較バー	前後の比較	グループ化された棒グラフ
アクション優先度マトリックス	工数と影響度に基づく結果	散布図
フルダッシュボード	1ページに複数のビジュアルを表示	HTML ダッシュボード

リクエストが曖昧な場合（「このデータをビジュアル化して」など）は、データに最適なビジュアルの種類を選びます。

• システムの健全性を示すステータス → ステータスストリップ
• 監査結果 → 重大度の分布＋アクション優先度マトリックス
• セッション履歴 → トレンドライン
• 前後のデータ → 比較バー
• 複数のデータ種別 → フルダッシュボード

---

ステップ 1：データを解析して正規化する

監査出力から

次の情報を抽出します。

• 結果 ID、重大度、カテゴリ
• メトリクスの合計（違反件数、カバレッジ率）
• コンポーネント名（依存関係グラフ用）
• トークン階層（カバレッジヒートマップ用）

保存済みの定期実行から

次の情報を抽出します。

• 日付とスキル名
• 実行ごとの主要メトリクス（トレンドラインで比較できるように揃える）
• 各レポートのトレンドセクションにある、実行間の差分

システムの健全性情報から

次の情報を抽出します。

• レポートに含まれる各側面のステータス（system-health には7つあります。数を決めつけず、実際に確認してください）
• 全体的な健全性ステータス
• 成熟度ステージ

すべてのデータをシンプルな構造に正規化します。

metrics: [{ label, value, max, category }]
timeseries: [{ date, metric, value }]
findings: [{ id, severity, category, effort?, impact? }]   # effort and impact only when the source report carries them
relationships: [{ source, target, weight }]

---

ステップ 2：ビジュアルを生成する

ステータスストリップ

レポートの順序に従って各側面につき1つのタイルを作成します。各タイルには、側面名、ステータスの語句、ステータスの色（🟢 Strong、🟡 Functional、🟠 Weak、🔴 Absent）と、主要な結果を1行で示すキャプションを含めます。ステータスは順序を持つラベルなので、ストリップであれば誤解を招きません。これらの上にレーダーチャートを重ねると、ラベルには存在しない大きさや面積があるかのように見えてしまいます。それでもユーザーがレーダーチャートを希望する場合は、軸にステータスの語句を表示して作成し、形状はあくまで説明用であることをキャプションに記載してください。

実装：カードを横並びにした HTML のフレックス行、または四角形を横並びにした SVG。

重大度の分布チャート

重大度別の結果の分布を示すドーナツチャートを作成します。

リングのセグメントには output-discipline の4段階の重大度のみを使用し、最も濃い色（Critical）から最も薄い色（Low）の順に並べます。これにより、グレースケールでも順序を読み取れます。各色は白い背景に対して少なくとも3:1のコントラスト比を確保し、すべてのセグメントにテキストラベルを付けます。

• Critical：濃い赤（#991B1B）
• High：オレンジ（#C2410C）
• Medium：アンバー（#C27C0E）
• Low：グレー（#6B7280）

バブルチャート、積み上げ棒グラフ、バッジなど、重大度を表示する場所では常に同じ4色を使用します。設定のブランドカラーを適用できるのは、重大度以外の系列のみです。

中央のテキスト：結果の合計件数。

実装：Chart.js のドーナツチャート、または SVG の円弧パス。

トレンドラインチャート

X 軸に時間、Y 軸にメトリクスを配置した折れ線グラフを作成します。追跡するメトリクスごとに1本の線を表示します。

次を含めます。

• 円で示したデータポイント
• 正確な値を表示するホバーツールチップ
• 設定されている場合は目標ライン
• トレンドが正か負かを示す注釈

実装：HTML 内の Chart.js 折れ線グラフ。

カバレッジヒートマップ

次の構成のグリッドを作成します。

• 行 = トークンカテゴリまたはコンポーネント領域
• 列 = カバレッジの各側面（primitive、semantic、component、documented、tested）
• セル = カバレッジのステータスに応じて色分け（緑 = カバー済み、アンバー = 一部、赤 = 未対応、グレー = 該当なし）

実装：背景色に CSS を使用した HTML テーブル、または SVG グリッド。

依存関係グラフ

コンポーネント間の関係を示す Mermaid フローチャートを作成します。

graph TD
    Button["Button (fan-in: 12)"]
    Card["Card (fan-in: 8)"]
    Modal["Modal (fan-in: 5)"]
    Button --> Card
    Button --> Modal
    Card --> ProductCard["ProductCard"]
    Card --> UserCard["UserCard"]

データがある場合は、健全性ステータスに応じてノードを色分けします。依存関係の重みは線の太さで示します。

実装：Mermaid.js 構文ブロック。

比較棒グラフ

各指標について、前後の値をグループ化した棒グラフを作成します。指標ごとに1つのグループを配置します（例：違反数、重大な問題の件数、カバレッジ率）。

色分け：

• 改善した指標：緑色の棒（違反数は改善後の値が改善前より小さい場合、カバレッジ率は改善後の値が改善前より大きい場合）
• 悪化した指標：赤色の棒
• 変化のない指標：灰色の棒

各棒グループの上に差分ラベルを表示します：「↓ 33%」または「↑ 5%」

実装：HTML で Chart.js のグループ化棒グラフを使用します。

アクション優先度マトリクス（根拠のある工数と影響がある場合のみ）

表示するすべての指摘に、ソースレポート由来の工数値と影響値がある場合に限り、マトリクスを表示します。工数は、監査で作成された見積もり表とその前提条件（たとえば token-audit のもの）から取得し、影響は指摘の深刻度から取得します。ソースに工数の数値がない場合は、マトリクスを省略し、テキストの要約でその旨を伝えます。グラフを作成するために、指摘へ工数を割り当ててはいけません。ダッシュボードに記載した架空の「8～12時間」は、スプリントでの確約になってしまいます。

以下を含む散布図を作成します。

• X 軸 = 工数（低 → 高）
• Y 軸 = 影響（低 → 高）
• 各点 = 1つの指摘。深刻度に応じて点のサイズを変えます
• 象限のラベル：「すぐに取り組める項目」（工数が低く、影響が大きい）、「戦略的投資」（工数も影響も大きい）、「軽微な改善」（工数も影響も小さい）、「慎重に検討」（工数が大きく、影響が小さい）

実装：HTML で Chart.js の散布図と象限オーバーレイを使用します。

完全なダッシュボード

複数のグラフを1つの HTML ページにまとめ、以下を含めます。

• システム名、日付、全体的な健全性ステータスを表示するヘッダー
• ヘッダーの下に、読者がどの程度懸念すべきか、最初に何を確認すべきかを示す見出し文。ソースレポート冒頭の内容を使用します
• グリッドレイアウト（デスクトップでは2列、モバイルでは1列）
• 比率に応じたサイズのグラフ
• 上部に3～5枚の主要指標カードを含む要約セクション
• インタラクティブなフィルター（保存済みの定期実行結果がある場合）：実行結果を切り替えるドロップダウン
• 最下部の「範囲」ブロック：ソースの指摘で調査した項目、調査していない項目（「未調査」）、および測定値ではなく報告値である項目を、ソースレポートから引き継ぎます

実装：すべてのデータをインラインに含めた単一の HTML ファイルを作成します。依存関係は Chart.js のみです。CDN 上の chart.js@4 は最新の 4.x を取得するため、オフライン環境や厳格なコンテンツセキュリティポリシー下では動作しません。そのため、ライブラリをインラインに含める（プロジェクトに存在する場合は node_modules/chart.js/dist/chart.umd.js を読み込む）か、バージョンを正確に固定し（npm view chart.js version）、integrity 属性を付けてください。どちらを使用したかをフッターに記載します。

---

ステップ 3：HTML ダッシュボードを作成する（完全なダッシュボードモードの場合）

ダッシュボードは単一の HTML ファイルです。構成：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[System Name] — Design System Health Dashboard</title>
  <script src="https://cdn.jsdelivr.net/npm/chart.js@[exact version]/dist/chart.umd.min.js" integrity="[sri hash]" crossorigin="anonymous"></script>
  
  <style>
    /* Inline styles — no external CSS */
    /* Use CSS Grid for layout */
    /* Responsive: 2 columns above 768px, 1 column below */
    /* Cards with subtle shadows for key metrics */
    /* Colour variables from config or defaults */
  </style>
</head>
<body>
  <header>
    
  </header>
  <p class="headline">
    
  </p>
  <section class="metrics-cards">
    
  </section>
  <section class="charts-grid">
    
  </section>
  <section class="scope">
    
  </section>
  <footer>
    <p>Generated by Design System Ops — visual-report</p>
    <p>[Date]</p>
  </footer>
  <script>
    // All chart configuration inline
    // Data embedded as JS objects
    // Chart.js instantiation for each chart
  </script>
</body>
</html>

主要指標カード

各カードには以下を表示します。

• 指標ラベル（例：「違反の合計」）
• 現在の値（大きなフォント）
• 前回の実行結果との差分（利用可能な場合。矢印と色を付けます）
• スパークラインの推移（データポイントが3つ以上ある場合）

レスポンシブ動作

• デスクトップ（>768px）：グラフは2列グリッド、カードは1行に3～5枚
• タブレット（768px）：グラフは2列グリッド、カードは折り返して1行に2枚
• モバイル（<768px）：1列にし、カードを縦に並べます

色のアクセシビリティ

• 意味を伝える際に、色だけに頼らないでください
• パターンを使用します（目標値には破線、実績値には実線）
• すべてのグラフ要素にラベルを付けます
• すべてのテキストでコントラスト比を 4.5:1 以上にします
• スクリーンリーダー向けに、各グラフの下にテキスト形式の要約を含めます

---

ステップ 4：出力

HTML ダッシュボードの場合

設定された出力ディレクトリにファイルを保存します。 [output_directory]/[system-name]-dashboard-[YYYY-MM-DD].html

個別のグラフ（SVG）の場合

各グラフを個別の SVG ファイルとして保存します。 [output_directory]/[chart-type]-[YYYY-MM-DD].svg

Mermaid 図の場合

埋め込み先の Markdown ドキュメントで使用できるよう、Mermaid 構文ブロックを会話内にそのまま出力します。

すべての形式に共通

視覚出力を見なくても指摘内容を把握できるよう、図表が示す内容のテキスト形式の要約も出力します。

Dashboard generated: agds-dashboard-2026-03-09.html

What the visuals show:
- Status strip: Strongest in Tokens (🟢 Strong), weakest in Documentation (🟠 Weak)
- Severity distribution: 12 findings — 2 Critical, 4 High, 4 Medium, 2 Low
- Trend: Violations decreased 33% since January
- Coverage: Feedback token category has zero coverage across all tiers
- Priority matrix: skipped, the source report carries no effort figures

---

他のスキルとの連携

監査スキルの実行後

監査が完了したら、「visual-report を実行して、これらの調査結果からグラフを生成してください」と提案します。

full-system-diagnostic エージェントの一部として

診断エージェントは、Phase 4 の後に visual-report を連鎖させ、診断全体の出力からダッシュボードを自動生成できます。

stakeholder-brief の補助として

ステークホルダー向けブリーフを生成するときは、「まず visual-report を実行し、ダッシュボードをブリーフに添付してください」と提案します。

定期実行の場合

保存済みレポートを recurring.output_directory から読み込み、実行ごとの傾向線を作成します。設定と定期実行に関するメモに、照合方法が記載されています。

---

品質チェック

• すべての値は入力内の調査結果または数値の出典をたどれます。不足データは不足として表示し、グラフを完成させるために補間や推定を行いません
• ダッシュボードは見出し文で始まり、「Not inspected」を含む Scope ブロックで終わります
• 重大度には、上記の色を使用した出力規律の4段階のみを使用します
• 広くサポートされている HTML、CSS、JavaScript のみを使用します
• 外部依存関係は Chart.js のみとし、インライン化するか、完全性ハッシュ付きで正確なバージョンを固定します
• 優先度マトリクスは、プロットするすべての調査結果について、元のレポートに工数と影響が記載されている場合にのみ表示します
• 色は WCAG AA のコントラスト比を満たします
• すべてのビジュアルにテキストによる要約を添えます
• ダッシュボードはデスクトップ、タブレット、モバイルに対応します
• データはインラインに埋め込みます。外部データの取得は行いません
• ファイルは正しいディレクトリに、正しい命名規則で保存します
• Mermaid 図は、GitHub、GitLab、Notion でレンダリングされる有効な構文を使用します
• 出典マーカーを含めます：「Generated by Design System Ops — visual-report」