@squadbase/vantage 0.6.2-dev1.3e69e88 → 0.6.2-dev1.48b34e1

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

@@ -14,12 +14,45 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 
 ### 追加
 
+- **アプリの表示言語 `lang`。** ルート `_layout.tsx` の `export const lang = "ja"`（リテラル）が `<html lang>` になります。
+  日本語のスライド・doc が文節の途中で折れなくなり、スライドのツールバーも日本語になります。未指定は従来どおり `"en"` です。
 - **`--host [addr]` と `--allowed-hosts <list|true>`** を `vantage dev` / `vantage preview`(SPA)に
   追加しました。Vite は `Host` ヘッダが `localhost` 以外のリクエストを 403 で拒否するため、
   サンドボックスのプレビュープロキシやトンネルなど**別のホスト名で前に立つもの**があると
   そのままでは届きませんでした。`--allowed-hosts` は環境変数 **`VANTAGE_ALLOWED_HOSTS`** でも
   渡せます(フラグが優先)。どちらも指定しなければ挙動は従来どおりです。詳細は
   [CLI リファレンス](cli-reference)を参照してください。
+- **型付きチャート 8 種**を `@squadbase/vantage/components` に追加しました。`LineChart` /
+  `AreaChart` / `BarChart` / `DonutChart`(ECharts で描画)は `data`・`index`・`categories` を
+  渡すだけで描け、`EChartsOption` を書く必要がありません。`BarList` / `CategoryBar` /
+  `ProgressCircle` / `Tracker` は SVG と Tailwind で描く軽い部品です。色は既定でテーマの
+  `--chart-1..5` に追従し、指定するときはトークン名(`"chart-1"`〜`"chart-5"`)か CSS 色を渡します。
+  `EChart` は型付きチャートで表せない図のための逃げ道として残ります。
+- **UI プリミティブ 10 種**を `@squadbase/vantage/ui` に追加しました: `Avatar`・`Pagination`・
+  `RadioGroup`・`AlertDialog`・`Drawer`・`Toast`(`<Toaster>` + `toast.add()`)・`Field`・
+  `Combobox`・`HoverCard`・`Kbd`。
+- **[コンポーネント](components)に一覧ギャラリー**を足しました。カテゴリで絞り込め、各部品の
+  `vantage add ui` コマンドをコピーできます。
+- **[ページの種類](page-types)**のガイドを足しました(`.csv` / `.xlsx` / `.slide.tsx` /
+  `.doc.tsx` の書き方と、ページにならないファイル)。
+
+### 変更
+
+- **`vantage add ui <name>` で `/ui` と `/components` の部品をすべて取り出せるようになりました。**
+  これまでコピーできたのは `data-table` だけでした。registry は `src/` から生成するようになり、
+  コピーの中の import は公開サブパスに書き換わっています(→ [UI とテーマ](ui-and-theming))。
+
+### 修正
+
+- **`.xlsx` のページで日付が 1 日ずれて表示されなくなりました。** Excel の日付はタイムゾーンを
+  持たないのに、ブラウザのタイムゾーンで表示していたため、UTC より西(アメリカなど)では
+  `2026-06-02` が `6/1` と前日に、時刻付きのセルは UTC より東(日本など)でも夜の時刻が翌日に
+  ずれていました。いまはどのタイムゾーンでもファイルに書かれた日付・時刻のまま表示します。
+- **ドキュメント(`.doc.tsx`)を画面で見るとき、本文が画面の端に付かなくなりました。** 画面表示用の
+  余白が無かったため、表示幅が本文の幅(`--doc-max-width`、既定 48rem)より狭いと本文が左右の端に
+  付き、見出しもヘッダーのすぐ下から始まっていました。いまは左右に 1.5rem、上に 3rem、下に 5rem の
+  余白を取ります。下を広めにしているのは、右下の「PDF として保存」ボタンに最後の行が隠れないように
+  するためです。広い画面での本文の幅と、印刷の見た目は変わりません。
 
 ## v0.6.2
 

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 つごとがページをまたぎません。セクション全体は途中で改ページされることがあります。

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

@@ -0,0 +1,56 @@
+# DocFigure
+
+> 図の約束事を 1 か所に。主張のタイトル、単位、図、出典つきのキャプション。
+
+図の約束事をまとめた block です。主張を書いたタイトル、単位、チャート（`children`）、出典と注記のキャプションを `figure` / `figcaption` で組みます。チャートは自由で、型付きグラフでも `EChart` でも画像でも構いません。出典と時点が無い数字は未完成として、`source` と `asOf` を最初から用意しています。
+
+```tsx
+import { DocFigure } from "@squadbase/vantage/doc";
+import type { DocFigureProps } from "@squadbase/vantage/doc";
+```
+
+> [!NOTE]
+> これは **本文やセクションの中に置く部品**です（`<Document>` 直下の 1 セクションではありません）。見出し・本文の大きさや幅は `<Document>` が決めるので、ここでは寸法を指定しません。 `children` はチャート（`ReactNode`）です。 ページ全体の組み方は [ドキュメント](page-types/doc) を参照してください。
+
+## props
+
+| Prop | Type | 説明 |
+| --- | --- | --- |
+| `title` | `string` | 図が示す主張を文で（「解約率は 2 か月連続で低下」）。主題（「解約率の推移」）にしない。**必須**。 |
+| `unit` | `string` | 単位・スケール（「単位: %」）。タイトルの直下に出る。定義や但し書きは `notes` に書く。 |
+| `number` | `number` | 図の番号。キャプションに「図 N」と出る。 |
+| `source` | `string` | データの出どころ。キャプションに「出典: …」と出る。 |
+| `asOf` | `string` | データを取った日。日付だけを書く（「2026-10-03」）。block が「データ時点」の語を付ける。 |
+| `notes` | `string[]` | 注記・定義。1 行 1 件。 |
+| `children` | `ReactNode` | チャート。列の全幅を使う。**必須**。 |
+
+## 使い方
+
+```tsx
+import { Document, DocFigure } from "@squadbase/vantage/doc";
+import { EChart, type EChartsOption } from "@squadbase/vantage/components";
+
+const option: EChartsOption = {
+  xAxis: { type: "category", data: ["7 月", "8 月", "9 月"] },
+  yAxis: { type: "value" },
+  series: [{ type: "line", data: [2.4, 2.1, 1.8] }],
+};
+
+<Document>
+  <DocFigure
+    number={1}
+    title="解約率は 2 か月連続で低下"
+    unit="単位: %"
+    source="課金システム"
+    asOf="2026-10-03"
+    notes={["解約率は、月初の契約数に対するその月の解約数の割合。"]}
+  >
+    <EChart option={option} height={240} ariaLabel="解約率の推移（7〜9 月）" />
+  </DocFigure>
+</Document>
+```
+
+## 注意
+
+- `children` のチャートには `title` を付けません。タイトルは `DocFigure` の `title` に書きます。チャートの読み上げ名が要るときは `ariaLabel` を使います。
+- 図は印刷時に 1 ページに収まるよう、ページをまたぎません。