@squadbase/vantage 0.6.2-stg.3a2ba98 → 0.7.0-dev1.19083f7

package/docs/ja/agent-skills.md

@@ -15,7 +15,7 @@ Vantage は **Claude Code の Agent Skills** を同梱しています。Skill
 | `vantage-app` | アプリの新規作成と、`index.tsx` 単体の SPA から `server/api`・ネストレイアウト・動的ルート・404/error を備えた fullstack への拡張 |
 | `vantage-add-feature` | ページ / API / UI / ブロックの追加(`vantage add` + `check` / `routes` までの一連) |
 | `vantage-slide` | `.slide.tsx` でスライドデッキを書く(1920×1080 キャンバスの縦方向の予算、タイプスケール、段階表示、トランジションとモーフ、pptx 書き出しの前提) |
-| `vantage-design` | 見た目の意図 `DESIGN.md` と値を持つ `styles.css` をまとめて作る / 更新する(配色・チャートの色・書体・ブランド合わせ。URL・ロゴ・資料・外部の DESIGN.md からの取り込み、コントラストの確認) |
+| `vantage-design` | テーマ(`styles.css` の値と配色・チャートの色・書体)を決めて適用する(ブランド合わせ。URL・ロゴ・資料・外部の DESIGN.md からの取り込み、コントラストの確認) |
 | `vantage-pitfalls` | 落とし穴リファレンス(Base UI ≠ Radix、`SelectValue` の挙動、クライアントから `server/` を import しない など) |
 | `project-storage` | Squadbase の Project Storage(アップロード済みファイル)をブラウザから扱う(一覧、画像 / 動画 / PDF の埋め込み、アップロード)。Squadbase 上で動くアプリ向け |
 

package/docs/ja/changelog.md

@@ -8,6 +8,90 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 > まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
 > ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
 
+## v0.7.0
+
+UI 部品とテーマを作り直し、KPI・チャート・スライド / ドキュメント向けの部品が大きく増えました。
+部品に組み込まれた文言の既定の言語と、既定のテーマの見た目が変わります(2026-11-01)。
+
+> [!WARNING]
+> **部品に組み込まれた文言と数値・日付の書式が `<html lang>` に従うようになり、未指定なら英語になりました。**
+> これまで `DataTable`(「データがありません」「前へ / 次へ」など)・`FilterBar`・`EChart` の操作ボタン・
+> スライドのツールバーは日本語で固定でした。**日本語のアプリはルート `_layout.tsx` に
+> `export const lang = "ja"` を書いてください。** `StatusBadge` も `label` を省くと status の文字列を
+> そのまま出すのではなく、言語に合わせたラベル(`success` →「正常」/ "Healthy")を出します。
+
+> [!WARNING]
+> **既定のテーマが変わりました。** `@squadbase/vantage/theme.css` の `--primary` が無彩色から青になり、
+> 角丸(`--radius`)が 0.625rem → 0.5rem、チャート色とカードの影(`--shadow-card`)も新しくなりました。
+> `styles.css` でトークンを上書きしているアプリは、上書きした値がそのまま使われます。トークンの削除・
+> 改名はありません。
+
+### 追加
+
+- **アプリの表示言語 `lang`。** ルート `_layout.tsx` の `export const lang = "ja"`(リテラル)が
+  `<html lang>` になり、部品の文言・書式、スライドのツールバーがその言語になります。日本語のスライド・
+  doc は文節の途中で折れなくなります。未指定は `"en"`、不正な値は `vantage check` が
+  `INVALID_APP_LANG` で警告します。
+- **KPI と書式の部品**を `@squadbase/vantage/components` に追加しました: `KpiCard`(比較・目標・推移・
+  見込み)、`Delta`、`UpdatedAt`、`SampleData`、`Legend`、`ChartFrame` と、`formatValue` /
+  `formatDate` / `formatDateRange` / `computeComparison` などの書式・比較の関数。`TrendIndicator` は
+  非推奨になりました(`Delta` を使ってください。当面は残ります)。
+- **型付きチャート**: `LineChart` / `AreaChart` / `BarChart` / `DonutChart` / `ScatterChart` /
+  `WaterfallChart` / `Heatmap`(ECharts)と、`BarList` / `CategoryBar` / `ProgressCircle` / `Tracker`
+  (SVG)。`data`・`index`・`categories` を渡すだけで描け、`format`・目標・しきい値・予測・注記・
+  強調を共通の props で指定できます。色は既定でテーマの `--chart-1..5` に追従します。`EChart` は
+  逃げ道として残ります。
+- **スライドとドキュメントの部品。** `@squadbase/vantage/slide` に `SlideCover`・`SlideKpiHero`・
+  `SlideKpiGrid`・`SlideChartInsight`・`SlideExecSummary`・`SlideScorecardTable` など、
+  `@squadbase/vantage/doc` に `DocReportHeader`・`DocKpiScorecard`・`DocKeyFindings`・`DocFigure`・
+  `DocDataTable`・`DocCallout` などを追加しました。
+- **UI プリミティブ 10 種**を `@squadbase/vantage/ui` に追加しました: `Avatar`・`Pagination`・
+  `RadioGroup`・`AlertDialog`・`Drawer`・`Toast`(`<Toaster>` + `toast.add()`)・`Field`・
+  `Combobox`・`HoverCard`・`Kbd`。
+- **既存部品の機能追加。** `DataTable` に CSV 書き出し・列ごとの書式としきい値・比較列・セル内の
+  スパークライン・サーバー側のページング(`rowCount` / `manualSorting` / `isLoading` など)、
+  `PageShell` に更新時刻や出典を置く `PageShellMeta`、`DateRangePicker` に今週・先週・過去 28 日間の
+  プリセット、`FilterBar` に「すべて」を足しました。
+- **テーマのトークンを追加しました**: 意味色 `--positive` / `--negative` / `--warning` / `--info` /
+  `--neutral`(それぞれ `-subtle` / `-fill` 付き)と `--shadow-card`。
+- **`vantage add ui` で取り出せる部品が増えました。** `/ui` と `/components` の全部品に加え、
+  `PairedChart`・`HistogramChart`・`BoxPlotChart`・`AttentionList` などはパッケージからは出さず、
+  `vantage add ui <name>` でコピーして使います。コピーの中の import は公開サブパスに書き換わり、
+  文言はページの言語で切り替わります。
+- **`--host [addr]` と `--allowed-hosts <list|true>`** を `vantage dev` / `vantage preview`(SPA)に
+  追加しました。サンドボックスのプレビュープロキシやトンネルなど、別のホスト名で前に立つものから
+  届くようになります。`--allowed-hosts` は環境変数 **`VANTAGE_ALLOWED_HOSTS`** でも渡せます
+  (フラグが優先)。どちらも指定しなければ挙動は従来どおりです(→ [CLI リファレンス](cli-reference))。
+- **`vantage check` の警告を 2 つ追加しました**: トークンを使わず色を直書きしている箇所
+  (`HARDCODED_COLOR`。データの意味を持つ色は `// vantage-ignore-color` で除外できます)と、長すぎる
+  `DESIGN.md`(`DESIGN_MD_TOO_LONG`)。どちらも警告で、ビルドは止めません。
+- **[コンポーネント](components)に一覧ギャラリー**と、**[ページの種類](page-types)**のガイドを
+  足しました。
+
+### 変更
+
+- **依存を更新しました**: Vite 8.3、`@vitejs/plugin-react` 6.1、Tailwind CSS 4.3.3、Hono 4.13 など。
+  `typescript`(5 以上)を任意の peer dependency として宣言しました。
+- **`vantage dev` で API(`server/`)を変えてもページ全体を再読み込みしなくなりました。** データだけを
+  取り直します。
+- **ホームのプレースホルダーのページは、`index.slide.tsx` などの新しいページに `/` を譲ります。**
+  雛形のまま手を入れていないプレースホルダーと新しいページが `/` で衝突しても `ROUTE_CONFLICT` に
+  なりません。
+- **`vantage doctor` が `bun.lock` を認識します。**
+
+### 修正
+
+- **`.xlsx` のページで日付が 1 日ずれて表示されなくなりました。** どのタイムゾーンでもファイルに
+  書かれた日付・時刻のまま表示します。
+- **ドキュメント(`.doc.tsx`)を画面で見るとき、本文の周りに余白を取るようになりました**(左右 1.5rem、
+  上 3rem、下 5rem。下は「PDF として保存」ボタンに最後の行が隠れないため)。印刷の見た目は変わりません。
+- **`EChart` の棒グラフで、ホバーすると棒が消える不具合を直しました。** データが変わらない再描画で
+  チャートがちらつかなくなり、データが変わったときは差分だけアニメーションします。
+- **狭い幅で `PageShell` のタイトルが縦に潰れなくなりました。** 日本語の本文でカナが細く表示されない
+  よう、既定のフォントに日本語のシステムフォントを足しました。
+- **書きかけの props(必須の配列が未指定など)でも部品が例外を出さなくなりました。**
+- **エディタ内のプレビューでもスライドを全画面表示できるようになりました。**
+
 ## v0.6.2
 
 ドキュメントのページを PDF として保存できるようになりました(2026-09-30)。

package/docs/ja/cli-reference.md

@@ -351,6 +351,35 @@ vantage dev --strict-port                  # 5173 が取れなければ起動し
 > また fullstack の `preview` は Node サーバーを 1 ポートに bind するだけなので**常に厳格**で、
 > `--no-strict-port` は効きません。
 
+## `--host` / `--allowed-hosts` — リバースプロキシの後ろで動かす
+
+`vantage dev` と `vantage preview`(SPA)は、既定では `localhost` にしか bind せず、`Host` ヘッダが
+`localhost` か bind したアドレス以外のリクエストを **403 で拒否**します(Vite の DNS リバインディング
+対策)。サンドボックスのプレビュープロキシ・トンネル・コンテナのネットワークなど、**別のホスト名で
+前に立つもの**があるときは、この 2 つを組み合わせて通します。
+
+```bash
+vantage dev --host                              # すべてのインターフェースで listen
+vantage dev --host 0.0.0.0                      # アドレスを明示(--host=:: の形も可)
+vantage dev --allowed-hosts preview.example.com # プロキシが名乗るホスト名を許可(カンマ区切りで複数)
+vantage dev --allowed-hosts true                # Host の検査そのものを無効化
+```
+
+| フラグ | 意味 |
+|---|---|
+| `--host [addr]` | 値なしなら**すべてのインターフェース**、値があればそのアドレスに bind する(Vite の `server.host`)|
+| `--allowed-hosts <list\|true>` | 受け付ける `Host` ヘッダの一覧(カンマ区切り)。`true` で検査を無効化(Vite の `server.allowedHosts`)|
+
+`--allowed-hosts` は環境変数 **`VANTAGE_ALLOWED_HOSTS`** でも渡せます(同じ書式)。サーバーを起動する
+側の仕組みがホスト名を知っている場合はそちらが便利です。フラグと環境変数の両方があれば**フラグが
+勝ちます**。どちらも無ければ Vite の既定のままで、これまでどおり `localhost` だけを受け付けます。
+
+> [!NOTE]
+> `--host` の値は次のトークンを取ります。`vantage --host dev` のように直後にコマンドやパスが来る
+> 書き方は値と取り違えるので、その場合は `--host=<addr>` か、末尾に `--host` を置いてください。
+> fullstack の `preview` は Node サーバーがすべてのインターフェースで listen し `Host` を検査しない
+> ので、どちらのフラグも効きません(その旨が表示されます)。
+
 ## dev のブラウザ出力 — 転送とオーバーレイ
 
 `vantage dev` は、ブラウザ側で起きたことを**開発ターミナルへ転送します**。既定で転送するのは

package/docs/ja/components.md

@@ -3,13 +3,15 @@
 > Vantage に同梱される shadcn/ui (Base UI) キットと、ダッシュボード用の複合コンポーネントのリファレンス。
 
 Vantage は **shadcn/ui** をそのまま同梱しています。インストールもコピーも不要で、import するだけで
-使えます。公開されている入り口は 3 つで、**サイドバーもこの 3 つで区切ってあります**。
+使えます。入り口は 5 つのサブパスで、**サイドバーもこの 5 つで区切ってあります**（`/slide` と `/doc` は、スライドとドキュメントのページの中身に使う block 用です）。
 
-| サブパス | 中身 | 件数 |
-| --- | --- | --- |
-| [`@squadbase/vantage/ui`](ui/button) | shadcn/ui のプリミティブ（Base UI 版）と、`cn()` などのユーティリティ | 37 |
-| [`@squadbase/vantage/components`](parts/page-shell) | それらを組み上げたダッシュボード部品 | 15 |
-| [`@squadbase/vantage/markdown`](markdown/markdown-renderer) | Markdown の描画だけ（重いので分離） | 1 |
+| サブパス | 中身 |
+| --- | --- |
+| [`@squadbase/vantage/ui`](ui/button) | shadcn/ui のプリミティブ（Base UI 版）と、`cn()` などのユーティリティ |
+| [`@squadbase/vantage/components`](parts/page-shell) | それらを組み上げたダッシュボード部品 |
+| [`@squadbase/vantage/markdown`](markdown/markdown-renderer) | Markdown の描画だけ（重いので分離） |
+| [`@squadbase/vantage/slide`](slide/slide-cover) | `.slide.tsx` の 1 枚の中身に置く block（表紙・要旨・KPI・グラフ・スコアカード・次の打ち手の 7 つ） |
+| [`@squadbase/vantage/doc`](doc/doc-report-header) | `.doc.tsx` の `<Document>` の中に並べる節・部品の block（8 つ） |
 
 ```tsx
 import { Button, Card, Badge } from "@squadbase/vantage/ui";
@@ -17,9 +19,28 @@ import { PageShell, DashboardCardPreset, EChart } from "@squadbase/vantage/compo
 import { MarkdownRenderer } from "@squadbase/vantage/markdown";
 ```
 
+## 一覧
+
+用途で絞り込めます。カードを開くと、動くプレビュー・import 文・props が見られます。
+
+## どちらを使うか
+
+似た役割のものが並んでいる組み合わせです。迷ったら左の列の条件で選んでください。
+
+| 迷いやすい組み合わせ | 選び方 |
+| --- | --- |
+| [`Badge`](ui/badge) / [`StatusBadge`](parts/status-badge) | 件数やタグなど**ただのラベル**は `Badge`。`active` / `failed` のような**レコードの状態**を色付きドットで示すなら `StatusBadge`（色は状態名から自動で決まる）。 |
+| [`ToggleGroup`](ui/toggle-group) / [`SegmentedControl`](parts/segmented-control) | 表示期間やビューの切り替えのような**単一選択**は `SegmentedControl`（値は `string`）。複数を同時に押せる**トグルの束**が要るときだけ `ToggleGroup`（値は常に配列）。 |
+| [`Select`](ui/select) / [`SearchableSelect`](parts/searchable-select) / [`MultiSelect`](parts/multi-select) / [`FilterBar`](parts/filter-bar) | 候補が**数個**なら `Select`。**多くて探したい**なら `SearchableSelect`、**複数選ぶ**なら `MultiSelect`。ページ上部に並ぶ**絞り込み一式**は、個別に置かず `FilterBar`（`FilterBarSelect` / `FilterBarMultiSelect`）でまとめて 1 つの値として扱う。 |
+| [`KpiCard`](parts/kpi-card) / [`Delta`](parts/delta) / [`MetricValue`](parts/metric-value) | KPI のタイル 1 枚なら `KpiCard`（値・増減・前期実績・結論の 1 文まで出る）。表のセルや見出しの横に**増減だけ**を置くなら `Delta`。`MetricValue` は書式を自分で決めた数値を大きく見せたいときだけ。`TrendIndicator` は非推奨。 |
+| [`Sparkline`](parts/sparkline) / [`EChart`](parts/echart) | 表のセルや KPI タイルの隅に置く、**軸も凡例もない小さな推移**は `Sparkline`。軸・ツールチップ・凡例のある**本格的なグラフ**は `EChart`。 |
+| [`Skeleton`](ui/skeleton) / [`DashboardCardSkeleton`](parts/dashboard-card) / [`Placeholder`](parts/placeholder) | **読み込み中**の任意の形は `Skeleton`、ダッシュボードのタイル 1 枚分なら `DashboardCardSkeleton`。`Placeholder` は読み込み中ではなく、**中身が仮データであること**を示す目印。 |
+| [`Loading`](ui/loading) / [`Empty`](ui/empty) / [`ErrorState`](ui/error-state) | データ取得の 3 状態に 1 つずつ対応する。**取得中**は `Loading`、**0 件**は `Empty`、**失敗**は `ErrorState`（`action` に再試行ボタンを置ける）。 |
+
 > [!NOTE]
 > UI キットは**パッケージから import して使う**のが基本です（コピーしません）。中身を書き換えたい
-> ときだけ [`vantage add`](cli-reference) で編集可能なソースを取り出します。
+> ときだけ [`vantage add ui`](cli-reference) で編集可能なソースを取り出します。各コンポーネントの
+> ページ冒頭に、import 文と取り出しコマンドをコピーできる行があります。
 
 ## Base UI ベースであること
 
@@ -53,87 +74,18 @@ Vantage の `theme.css` は両方の綴りを受ける custom variant を定義
 
 shadcn/ui のプリミティブです。名前も props も shadcn/ui のものと同じなので、
 [shadcn/ui のドキュメント](https://ui.shadcn.com/docs/components) もそのまま参考になります。
-サイドバーはアルファベット順ですが、ここでは用途で並べています。
-
-### フォームと入力
-
-[`Button`](ui/button) ·
-[`Input`](ui/input) ·
-[`InputGroup`](ui/input-group) ·
-[`Textarea`](ui/textarea) ·
-[`Label`](ui/label) ·
-[`Select`](ui/select) ·
-[`Checkbox`](ui/checkbox) ·
-[`Switch`](ui/switch) ·
-[`Slider`](ui/slider) ·
-[`Toggle`](ui/toggle) ·
-[`ToggleGroup`](ui/toggle-group) ·
-[`Calendar`](ui/calendar) ·
-[`Command`](ui/command)
-
-### レイアウトとナビゲーション
-
-[`Card`](ui/card) ·
-[`Tabs`](ui/tabs) ·
-[`Separator`](ui/separator) ·
-[`ScrollArea`](ui/scroll-area) ·
-[`Sidebar`](ui/sidebar) ·
-[`Breadcrumb`](ui/breadcrumb) ·
-[`Accordion`](ui/accordion) ·
-[`Collapsible`](ui/collapsible)
-
-### データ表示
-
-[`Table`](ui/table) ·
-[`Badge`](ui/badge) ·
-[`Progress`](ui/progress)
-
-### オーバーレイ
-
-[`Dialog`](ui/dialog) ·
-[`Sheet`](ui/sheet) ·
-[`Popover`](ui/popover) ·
-[`Tooltip`](ui/tooltip) ·
-[`DropdownMenu`](ui/dropdown-menu)
-
-### 状態表示
-
-[`Alert`](ui/alert) ·
-[`Skeleton`](ui/skeleton) ·
-[`Spinner`](ui/spinner) ·
-[`Loading`](ui/loading) ·
-[`Empty`](ui/empty) ·
-[`ErrorState`](ui/error-state)
-
 `Loading` / `Empty` / `ErrorState` の 3 つだけは shadcn/ui にはなく、Vantage が足したものです。
 
-### ユーティリティ
-
-[`cn()`](ui/cn) · [`useIsMobile()`](ui/use-is-mobile)
-
 ## `@squadbase/vantage/components`
 
-`ui/` を組み上げた、ダッシュボード向けの複合部品です。
+`ui/` を組み上げた、ダッシュボード向けの複合部品です。ページ枠（`PageShell` / `AppShell`）、
+タイル（`DashboardCard`）、表（`DataTable`）、グラフ（`EChart` / `Sparkline` / `FunnelSteps`）、
+フィルタ（`FilterBar` / `DateRangePicker` など）、KPI 表示が入っています。部品の正本は SquadKit で、
+Vantage はそれを再エクスポートしています。
 
-| コンポーネント | 概要 |
-| --- | --- |
-| [`PageShell`](parts/page-shell) | ヘッダー帯・サマリー・本文からなるページ枠 |
-| [`AppShell`](parts/app-shell) | ナビゲーション定義を渡すだけのアプリ枠 |
-| [`SectionHeader`](parts/section-header) | セクション見出しとアクション |
-| [`DashboardCard`](parts/dashboard-card) | ダッシュボードのタイル（プリセットとスケルトン付き） |
-| [`DataTable`](parts/data-table) | 並べ替え・検索・ページング・選択を備えた表 |
-| [`EChart`](parts/echart) | Apache ECharts のラッパー |
-| [`FunnelSteps`](parts/funnel-steps) | ファネルの棒表示 |
-| [`Sparkline`](parts/sparkline) | セルやタイルに置くインラインの推移グラフ |
-| [`FilterBar`](parts/filter-bar) | フィルタ一式を 1 つの値で扱う行 |
-| [`DateRangePicker`](parts/date-range-picker) | プリセット付きの期間選択 |
-| [`SegmentedControl`](parts/segmented-control) | 単一選択のセグメント |
-| [`SearchableSelect`](parts/searchable-select) | 検索できる単一選択 |
-| [`MultiSelect`](parts/multi-select) | 検索できる複数選択 |
-| [`MetricValue`](parts/metric-value) | KPI の数値と単位 |
-| [`TrendIndicator`](parts/trend-indicator) | 増減の矢印と変化率 |
-| [`StatusBadge`](parts/status-badge) | ドット付きステータスバッジ |
-| [`Placeholder`](parts/placeholder) | 仮データであることを示すインラインの目印 |
+KPI は [`KpiCard`](parts/kpi-card)、増減は [`Delta`](parts/delta)（`comparison` と
+`polarity` を渡す）で示します。[`TrendIndicator`](parts/trend-indicator) は非推奨です。数値の
+書式と増減の計算は [format / comparison](parts/format) にまとまっています。
 
 ## `@squadbase/vantage/markdown`
 
@@ -141,6 +93,15 @@ shadcn/ui のプリミティブです。名前も props も shadcn/ui のもの
 Markdown 描画は Shiki の全言語文法を抱えており、`components` のバレルに混ぜるとビルド出力が
 10 MB 以上増えるため、意図的に分けてあります。
 
+## `@squadbase/vantage/slide` と `@squadbase/vantage/doc`
+
+[スライド](page-types/slide)と[ドキュメント](page-types/doc)のページに置く block です。`/components` とは別のサブパスで、`vantage add` のコピー対象にもなりません（import して使います）。
+
+- **slide**: 1 枚の `<Slide>` の中身（`<Slide>` 自体は持ちません）。[`SlideCover`](slide/slide-cover) / [`SlideExecSummary`](slide/slide-exec-summary) / [`SlideKpiHero`](slide/slide-kpi-hero) / [`SlideKpiGrid`](slide/slide-kpi-grid) / [`SlideChartInsight`](slide/slide-chart-insight) / [`SlideScorecardTable`](slide/slide-scorecard-table) / [`SlideNextActions`](slide/slide-next-actions) / [`SlideSection`](slide/slide-section) / [`SlideComparison`](slide/slide-comparison) / [`SlideChartFull`](slide/slide-chart-full)
+- **slide parts**: 1 枚の中で使う部品（1 枚まるごとではありません）。[`SlideHeading`](slide/slide-heading) / [`SlideSourceLine`](slide/slide-source-line) / [`SlideColumns`, `SlideColumn`](slide/slide-columns)
+- **doc**: `<Document>` の中に並べる節や部品（`DocFigure` / `DocDataTable` / `DocCallout` は節の中に置く部品）。[`DocReportHeader`](doc/doc-report-header) / [`DocExecutiveSummary`](doc/doc-executive-summary) / [`DocKpiScorecard`](doc/doc-kpi-scorecard) / [`DocFigure`](doc/doc-figure) / [`DocDataTable`](doc/doc-data-table) / [`DocCallout`](doc/doc-callout) / [`DocKeyFindings`](doc/doc-key-findings) / [`DocActionItems`](doc/doc-action-items) / [`DocNotesAndSources`](doc/doc-notes-and-sources)
+- **doc parts**: 文中に置く部品（slide でも使えます）。[`DeltaText`](doc/delta-text)
+
 ## 組み合わせる
 
 ```tsx
@@ -154,9 +115,8 @@ import {
   PageShellHeaderEnd,
   PageShellActions,
   PageShellContent,
+  KpiCard,
   DashboardCardPreset,
-  MetricValue,
-  TrendIndicator,
   EChart,
   type EChartsOption,
 } from "@squadbase/vantage/components";
@@ -184,17 +144,25 @@ export default function Overview() {
 
       <PageShellContent>
         <div className="grid gap-4 md:grid-cols-3">
-          <DashboardCardPreset title="売上">
-            <MetricValue className="my-0">¥1,240,000</MetricValue>
-            <TrendIndicator value={12.4} direction="up" />
-          </DashboardCardPreset>
-          <DashboardCardPreset title="新規顧客">
-            <MetricValue className="my-0">128</MetricValue>
-            <TrendIndicator value={3.1} direction="down" />
-          </DashboardCardPreset>
-          <DashboardCardPreset title="解約率">
-            <MetricValue className="my-0">2.1%</MetricValue>
-          </DashboardCardPreset>
+          <KpiCard
+            label="売上"
+            value={1_240_000}
+            format="currency"
+            comparison={{ previous: 1_103_000, vs: "prior-period" }}
+          />
+          <KpiCard
+            label="新規顧客"
+            value={128}
+            format="number"
+            comparison={{ previous: 132, vs: "prior-period" }}
+          />
+          <KpiCard
+            label="解約率"
+            value={0.021}
+            format={{ type: "percent", digits: 1 }}
+            comparison={{ previous: 0.026, vs: "prior-period" }}
+            polarity="lower-is-better"
+          />
         </div>
 
         <DashboardCardPreset title="月次売上" className="mt-4">
@@ -214,16 +182,15 @@ export default function Overview() {
 
 ## ソースを編集したいとき
 
-コンポーネントの中身そのものを変えたい場合は、編集可能なコピーを取り出します。
+コンポーネントの中身そのものを変えたい場合は、編集可能なコピーを取り出します。名前は各ページ冒頭の
+「ソースを取り出す」の行に出ているものです。
 
 ```bash
-vantage add ui data-table        # 編集可能な DataTable を components/ へ
+vantage add ui data-table        # 編集可能な DataTable を components/ui/ へ
 vantage add block sales-overview
 ```
 
-> [!NOTE]
-> 現行プロトタイプで `vantage add` がコピーできるのは `data-table`（ui）と `sales-overview`（block）
-> のみです。その他のコンポーネントは import 専用です。
+`cn()` と `useIsMobile()`、`@squadbase/vantage/markdown` は取り出しの対象外で、import 専用です。
 
 ## このページの読み方
 

package/docs/ja/doc/delta-text.md

@@ -0,0 +1,40 @@
+# DeltaText
+
+> [部品] 文中に置く増減。▲ ▼ と符号つきの値。ドキュメントでもスライドでも。
+
+増減を文中に置くインラインの `span` です。印や符号（「▲ +3.2%」）で向きが分かるので、印刷や色覚の違いでも読めます。色は良い・悪いを足すだけです。文字サイズは指定せず、置いた行に従います。ドキュメントとスライドのどちらでも使える**部品**で、1 節や 1 枚の block ではありません。
+
+```tsx
+import { DeltaText } from "@squadbase/vantage/doc";
+import type { DeltaTextProps } from "@squadbase/vantage/doc";
+// スライドでも同じものを使える
+// import { DeltaText } from "@squadbase/vantage/slide";
+```
+
+> [!NOTE]
+> これは **文中に置く部品**です。自分では寸法も文字サイズも持たず、置いた行の大きさに従います。ダッシュボード用の `Delta` とは別物です。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `value` | `number \| null` |  | 増減そのもの。向きは符号で決まる。`null` は「—」。**必須**。 |
+| `format` | `ValueFormat` |  | 値の整形（`"percent"` / `"currency"` など）。符号つきで出る。 |
+| `betterWhen` | `"up" \| "down"` | `"up"` | どちらの向きが良いか。色が決まる。解約率・コストは `"down"`。 |
+| `comparisonLabel` | `string` |  | 比較相手の名前（「前月比」）。増減の前に薄く出る。 |
+
+## 使い方
+
+```tsx
+import { DeltaText } from "@squadbase/vantage/doc";
+
+<p>
+  9 月の売上は 5.4 億円でした（<DeltaText value={0.074} format="percent" comparisonLabel="前月比" />）。
+  解約率は 1.8% です（<DeltaText value={-0.006} format="percent" betterWhen="down" comparisonLabel="前月比" />）。
+</p>
+```
+
+## 注意
+
+- 0 は「→」で薄い色になります。
+- 読み上げ用の語（「増」「減」「横ばい」「改善」「悪化」）は固定の日本語です。

package/docs/ja/doc/doc-action-items.md

@@ -0,0 +1,49 @@
+# DocActionItems
+
+> 次にやること。内容・担当・期限・期待する効果・優先度。
+
+推奨する対応を並べるセクションです。内容・担当・期限・期待する効果・優先度を出します。既定の `table` は表、`asks` は読み手へのお願い（紹介・判断・採用など）を短い箇条書きにします。優先度は高・中・低の語だけで、バッジや色は付きません。
+
+```tsx
+import { DocActionItems } from "@squadbase/vantage/doc";
+import type { DocActionItemsProps, DocActionItem, DocActionPriority } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **`<Document>` 直下に並べる 1 セクション分**です。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `action` は `ReactNode` で、Markdown 文字列は解釈されません。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` | `"推奨する対応"` | 見出しの文言。 |
+| `headingLevel` | `2 \| 3` | `2` | 見出しのレベル。`<Document>` 直下は 2、別セクションの中は 3。 |
+| `items` | `DocActionItem[]` |  | 対応。重要なものから。**必須**。 |
+| `items[].action` | `ReactNode` |  | やること。**必須**。 |
+| `items[].owner` | `string` |  | 担当。 |
+| `items[].due` | `string` |  | 期限。書いたまま出る（「2026-11-15」「11 月末」）。 |
+| `items[].impact` | `string` |  | 期待する効果（「解約率 −0.5pt」）。`table` だけに出る。 |
+| `items[].priority` | `"high" \| "medium" \| "low"` |  | 優先度。高・中・低の語で出る（高は太字）。`table` だけに出る。 |
+| `variant` | `"table" \| "asks"` | `"table"` | 表か、読み手へのお願いの箇条書きか。 |
+
+## 使い方
+
+```tsx
+import { Document, DocActionItems } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocActionItems
+    items={[
+      { action: "法人プランの導入支援を増員する", owner: "CS 部", due: "2026-11-15", impact: "解約率 −0.5pt", priority: "high" },
+      { action: "紹介プログラムの特典を見直す", owner: "マーケティング部", due: "11 月末", impact: "紹介経由の新規 +10 社", priority: "medium" },
+      { action: "料金ページの文言を改善する", owner: "プロダクト部", priority: "low" },
+    ]}
+  />
+</Document>
+```
+
+## 注意
+
+- `due` は書いたまま表示されます（「2026-11-15」「11 月末」）。値の無い担当・期限・効果は「—」になります。
+- `variant="asks"` は担当と「`due` まで」だけを添えます（例: 「（CS 部・11 月末 まで）」）。効果と優先度は出しません。
+- 印刷時、`asks` は項目 1 つごとにページをまたぎません。

package/docs/ja/doc/doc-callout.md

@@ -0,0 +1,38 @@
+# DocCallout
+
+> 本文の中の囲み。補足・示唆・注意・決定事項。
+
+読み手に見落とされたくない 1 点を囲んで示す block です。`role="note"` の `div` に、種類ごとの意味色の左罫線が付きます（決定事項は中立色）。種類は「注意」「示唆」のような語でも表示されるので、色だけに頼りません。飾りには使いません。
+
+```tsx
+import { DocCallout } from "@squadbase/vantage/doc";
+import type { DocCalloutProps, DocCalloutKind } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **本文やセクションの中に置く部品**です（`<Document>` 直下の 1 セクションではありません）。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `children` は `string` か `ReactNode` で、Markdown 文字列は解釈されません。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `kind` | `"note" \| "insight" \| "warning" \| "decision"` | `"note"` | 種類。補足 / 示唆 / 注意 / 決定事項。 |
+| `title` | `string` |  | 囲みの見出し（1 行）。渡すと「<種類の語>: <title>」と出る。省くと種類の語だけが出る。種類の語と同じ文字列を渡したときも 1 回だけ出る。 |
+| `children` | `ReactNode` |  | 本文。`string` なら段落になる。Markdown 文字列は解釈されない。**必須**。 |
+
+## 使い方
+
+```tsx
+import { Document, DocCallout } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocCallout kind="warning" title="9 月の数値は速報値">
+    10 月 10 日の確定で変わることがあります。
+  </DocCallout>
+</Document>
+```
+
+## 注意
+
+- 種類の語（「補足」「示唆」「注意」「決定事項」）は block が付けます。`title` にも同じ語を書くと重複するので、見出しの内容だけを書きます。
+- 印刷時は 1 ページに収まるよう、ページをまたぎません。

package/docs/ja/doc/doc-data-table.md

@@ -0,0 +1,60 @@
+# DocDataTable
+
+> 印刷物の表に要る注記つきの表。タイトル・単位・合計行・脚注・出典。
+
+印刷物の表に必要な要素を揃えた表です。タイトル、単位、右揃えの数値、合計行、強調行、脚注、出典を出します。素の `table` なので、スタイルと印刷時の行の分割回避は `<Document>` が担います（並べ替えやスクロールが要る画面向けの表は `DataTable`）。
+
+```tsx
+import { DocDataTable } from "@squadbase/vantage/doc";
+import type { DocDataTableProps, DocTableColumn, DocTableRow, DocTableCell } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **本文やセクションの中に置く部品**です（`<Document>` 直下の 1 セクションではありません）。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 セルは文字列か数値で、`ReactNode` は渡せません。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | 表のタイトル（表の上のキャプション）。 |
+| `unit` | `string` | 単位・スケール（「単位: 百万円」）。タイトルがあれば「（単位: 百万円）」と続く。 |
+| `columns` | `DocTableColumn[]` | 列（`{ key; label; format?: ValueFormat; align?: "left" \| "right" \| "center" }`）。`format` を省くと桁区切りの数値。`align` を省くと数値の列は右揃え、それ以外は左揃え。**必須**。 |
+| `rows` | `DocTableRow[]` | 行。`columns` の `key` を持つオブジェクト。セルは文字列か数値（`null` / `undefined` / 空文字は「—」）。**必須**。 |
+| `total` | `DocTableRow` | 合計行（`tfoot`）。`rows` と同じキーで書く。 |
+| `highlightRows` | `number[]` | 太字にする行の index（0 始まり、`rows` の添字）。 |
+| `footnotes` | `{ mark: string; text: string }[]` | 脚注。セルの文字列に同じ `mark`（「※1」）を書くと対応する。 |
+| `source` | `string` | 出典。キャプションに「出典: …」と出る。 |
+| `asOf` | `string` | データを取った日。日付だけを書く（「2026-10-03」）。block が「データ時点」の語を付ける。 |
+
+## 使い方
+
+```tsx
+import { Document, DocDataTable } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocDataTable
+    title="部門別の売上"
+    unit="単位: 百万円"
+    columns={[
+      { key: "dept", label: "部門" },
+      { key: "sales", label: "売上", format: "number" },
+      { key: "share", label: "構成比", format: { type: "percent", digits: 1 } },
+    ]}
+    rows={[
+      { dept: "法人営業", sales: 312, share: 0.58 },
+      { dept: "パートナー", sales: 148, share: 0.27 },
+      { dept: "オンライン ※1", sales: 80, share: 0.15 },
+    ]}
+    total={{ dept: "合計", sales: 540, share: 1 }}
+    highlightRows={[0]}
+    footnotes={[{ mark: "※1", text: "9 月から集計対象に追加" }]}
+    source="会計システム"
+    asOf="2026-10-03"
+  />
+</Document>
+```
+
+## 注意
+
+- 数値は `tabular-nums` で桁が揃い、値が無いセルは「—」になります。
+- 印刷時は行ごとにページをまたぎません。長い表は行の間で改ページされ、キャプション（脚注・出典）は 1 ページにまとまります。

package/docs/ja/doc/doc-executive-summary.md

@@ -0,0 +1,64 @@
+# DocExecutiveSummary
+
+> 結論を先に書く要旨。結論 1 文、要点 3〜5 個、任意で主要な数字。
+
+結論を先に書く（BLUF）要旨のセクションです。結論の 1 文、番号付きの要点 3〜5 個、任意で最大 3 つの主要な数字を出します。数字の増減は渡した `delta` の符号から向きを決め、▲▼ と符号を必ず出すので、色が見えなくても向きが分かります。
+
+```tsx
+import { DocExecutiveSummary } from "@squadbase/vantage/doc";
+import type { DocExecutiveSummaryProps, DocSummaryMetric } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **`<Document>` 直下に並べる 1 セクション分**です。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `conclusion` と `points` は `string` か `ReactNode` で、Markdown 文字列は解釈されません。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | Default | 説明 |
+| --- | --- | --- | --- |
+| `title` | `string` | `"要旨"` | 見出しの文言。 |
+| `headingLevel` | `2 \| 3` | `2` | 見出しのレベル。`<Document>` 直下は 2、別セクションの中は 3。 |
+| `conclusion` | `ReactNode` |  | 結論を 1 文で。太字で出る。**必須**。 |
+| `points` | `ReactNode[]` |  | 裏付ける要点。3〜5 個、重要な順。番号付きで出る。**必須**。 |
+| `metrics` | `DocSummaryMetric[]` |  | 主要な数字（最大 3、超えた分は無視）。 |
+| `metrics[].label` | `string` |  | 指標の名前。 |
+| `metrics[].value` | `number \| null` |  | 値。`null` は「—」。 |
+| `metrics[].format` | `ValueFormat` |  | `value` の書式（`"currency"`、`{ type: "percent", digits: 1 }` など）。 |
+| `metrics[].display` | `string` |  | 渡すと値の代わりにこの文字列を出す（「約 5,400 万円」）。 |
+| `metrics[].delta` | `{ value: number; format?: ValueFormat }` |  | 比較先からの増減そのもの（現在値 − 比較値）。向きは符号で決まり、▲▼ と符号を必ず出す。省くと比較を出さない。`format` を省くと指標の `format` を使う。 |
+| `metrics[].comparisonLabel` | `string` | `"前期比"` | 比較の名前（「前月比」）。 |
+| `metrics[].betterWhen` | `"up" \| "down"` | `"up"` | どちらに動くと良いか。解約率やコストは `"down"`。色は良し悪しだけを足す。 |
+
+## 使い方
+
+```tsx
+import { Document, DocExecutiveSummary } from "@squadbase/vantage/doc";
+
+<Document>
+  <DocExecutiveSummary
+    conclusion="9 月の売上は計画を上回ったが、新規獲得は目標に届いていない。"
+    points={[
+      "売上は 5,390 万円で、計画比 +3.7%。",
+      "解約率は 1.8% まで下がり、3 か月連続で改善。",
+      "新規獲得は 38 社で、目標の 50 社に未達。",
+    ]}
+    metrics={[
+      { label: "売上", value: 53_900_000, format: "currency", delta: { value: 3_700_000 }, comparisonLabel: "前月比" },
+      {
+        label: "解約率",
+        value: 0.018,
+        format: { type: "percent", digits: 1 },
+        delta: { value: -0.003, format: { type: "number", digits: 1, unit: "pt", divisor: 0.01 } },
+        comparisonLabel: "前月比",
+        betterWhen: "down",
+      },
+    ]}
+  />
+</Document>
+```
+
+## 注意
+
+- 下がることが良い指標は `betterWhen: "down"` にします（色の良し悪しが反転します。▲▼ と符号は実際の向きのままです）。
+- `delta` は比較値ではなく増減そのものです。比率の指標（解約率など）は、例のように `format` で `pt` 表記にすると相対変化と読み違えません。
+- 印刷時は、要点 1 つごと・主要な数字のタイル 1 つごとがページをまたぎません。セクション全体は途中で改ページされることがあります。