id: kpi-cards
name:
  ja: "KPIカード（実績サマリ）"
  en: "KPI Cards (Performance Summary)"
purpose:
  ja: "代表KPIの現在値・前期比・目標達成・推移を一つの主分析面で示し、残りを比較ledgerへ整理する。実データ系列から SVG スパークラインを自動生成し、目標を破線で重ねて達成/未達を自動判定する。解約率のような「下がるほど良い」指標も betterWhen で正しく着色される"
  en: "One headline figure with its change, its target and its trend on a single analysis face, the rest arranged into a comparison ledger. Sparklines are drawn from the real series and the target laid over them"
status: published
# 索引カードの図版。pnpm layout:render が原本から描く。
still: ./still.png
category: metrics
catalogOrder: 30
jobs:
  - measure-change
useCases:
  - kpi
layoutKinds:
  - grid
tags: [kpi, metrics, dashboard, sparkline, data-driven, interactive]
whenToUse:
  - ja: "施策・システム導入後の効果測定サマリ（月次・四半期レビュー）"
    en: "Measuring the effect of an initiative after it lands (monthly or quarterly)"
  - ja: "経営会議やステアリングコミッティ冒頭の実績ダッシュボード"
    en: "The dashboard that opens a steering committee"
  - ja: "目標に対する現在地を指標横断で一覧したい場合"
    en: "Seeing where every indicator stands against its target at once"
  - ja: "数値そのものが主役で、構造や関係性を示す必要がない場合"
    en: "When the numbers themselves are the subject, not the structure behind them"
avoidWhen:
  - ja: "指標同士の因果関係や階層構造を説明したい場合"
    en: "Explaining cause or hierarchy between indicators"
  - ja: "増減要因の内訳を起点から終点まで示したい場合"
    en: "Breaking a change down from its start to its end"
requiredInputs:
  - ja: "指標名"
    en: "What each indicator is"
  - ja: "時系列の実績値"
    en: "Its actual values over time"
  - ja: "目標値と改善方向"
    en: "Its target, and which direction is better"
relatedLayouts: [waterfall, heatmap, conversion-funnel]
dataSchema:
  title: "string — スライドタイトル。結論を書くメッセージラインを推奨"
  subtitle: "string（任意）— 補足・出典など。系列の期間を書くことを推奨"
  metrics: "{ label, series, format?, deltaMode?, deltaSuffix?, target?, betterWhen?, note?, highlight? } の配列。4件前後が読みやすい"
  metrics[].series: "number[] — 実データ系列（古い順、最後が現在値、2点以上）。スパークライン・現在値・前期比の唯一の出典。表示用の数値を別に持たせない"
  metrics[].format: "{ prefix?, suffix?, decimals?, showSign? } — 現在値の表示形式。例: { prefix: \"¥\", suffix: \"M\", decimals: 1 } → ¥12.4M。decimals 省略時は series と target が持つ桁数から推論する（最大4桁）ので、桁を固定したいときだけ書く。showSign は NPS のような増減幅が本体の指標のみ true"
  metrics[].deltaMode: "\"relative\"（既定・変化率%）または \"absolute\"（実数差）。%やptの指標は absolute + deltaSuffix \"pt\" を使う（3.3%→3.8% は「+15%」ではなく「+0.5pt」）"
  metrics[].deltaSuffix: "string（任意）— absolute のときの前期比の単位（例: \"pt\"）。relative では無視される"
  metrics[].target: "number（任意）— 目標値。series と同じ単位の生値。スパークライン上に破線で描かれ、達成/未達バッジを自動判定する"
  metrics[].betterWhen: "\"up\"（既定）または \"down\"。down は解約率など下がるほど良い指標。前期比の色と目標達成判定の両方に効く"
  metrics[].note: "string（任意）— カード群の下の補足欄で明示的に展開される詳細（要因・前提・出典）"
  metrics[].highlight: "boolean（任意）— 最重要の1件のみ true。その指標だけが大型sparklineを持つ主分析面になり、残りは比較ledgerへ置かれる。省略時は先頭を暗黙に昇格せず全件同格"
sources: []