@squadbase/vantage-template 0.1.1-dev1.ac4fa22 → 0.1.1-dev1.da9fa09

package/base-template/.squadbase/skills/vantage-slide/references/tokens.md

@@ -0,0 +1,87 @@
+# デザイントークンと書体
+
+## トークンの解決順
+
+スライドの色と書体は CSS カスタムプロパティ `--slide-*` から来ます。値は 3 段で解決されます:
+
+1. **`theme.css`（フレームワーク）** —— `--slide-bg: var(--background)` のように、アプリ自身の
+   トークンへの**別名**が張ってあります。CSS 変数は遅延解決なので、これだけでデッキは
+   アプリのライト / ダークの切り替えに自動で追従します
+2. **アプリの `styles.css`** —— アプリがトークンを上書きしていれば、デッキもそれに従います
+3. **`<SlideDeck theme={{ … }}>`** —— そのデッキのルートにインラインで書かれ、上の 2 つに勝ちます
+
+| プロパティ | CSS 変数 | 既定 |
+| --- | --- | --- |
+| `bg` | `--slide-bg` | `var(--background)` |
+| `fg` | `--slide-fg` | `var(--foreground)` |
+| `accent` | `--slide-accent` | `var(--primary)` |
+| `muted` | `--slide-muted` | `var(--muted-foreground)` |
+| `fontDisplay` | `--slide-font-display` | 日本語を含むシステムスタック |
+| `fontBody` | `--slide-font-body` | `var(--slide-font-display)` |
+| `sizeHero` | `--slide-size-hero` | `168px` |
+| `sizeBody` | `--slide-size-body` | `36px` |
+| `radius` | `--slide-radius` | `var(--radius)` |
+
+```tsx
+<SlideDeck theme={{ bg: "#0f172a", fg: "#f8fafc", accent: "#fbbf24" }}>
+```
+
+**使うときは変数で参照します** —— `color: "var(--slide-fg)"`、`fontSize: "var(--slide-size-hero)"`。
+`theme` に渡した値を直接書かないこと。変数経由にしておけば、`theme` を 1 行変えるだけでデッキ全体が
+追従します。
+
+**`theme` に無い色はプレーンな const に置く**（`const muted = "#94a3b8"`）。`theme` は
+「デッキの土台となる 3〜4 色」のためのもので、パレット全部を入れる場所ではありません。
+
+## ダークモード
+
+`theme` を渡さないデッキは、アプリのトークンをそのまま使います —— つまり `.dark` /
+`[data-theme="dark"]` が祖先に付いていればダークで描かれます。**明暗の両方を自分で管理する必要は
+ありません。**
+
+`theme` に具体的な色（`bg: "#0f172a"`）を書いた瞬間、そのデッキは明暗に追従しなくなります。
+これは意図的です —— 配色を決め打ちしたデッキは、どちらのモードでもその配色であるべきだからです。
+追従させたいなら `theme` を渡さないこと。
+
+## 書体
+
+**既定はシステムスタックで、まずこれを使ってください。** 日本語を含むスタックが最初から入っています。
+
+webfont が本当に必要なとき（ブランドフォント、あるいはシステムのカバーが薄い言語）:
+
+- **`<head>` に 1 回だけ、冪等に読み込む。** スライドコンポーネントの中でスタイルシートを描かないこと。
+  切り替え中は 2 枚のスライドが同時にマウントされ、pptx 書き出しでは全スライドが同時にマウントされます
+  —— コンポーネントの中で `<link>` を描くと `@font-face` の集合が**マウント数だけ**登録されます。
+  `.slide.tsx` のモジュールのトップレベルから 1 回だけ注入します:
+
+  ```tsx
+  const FONT_HREF = "https://fonts.googleapis.com/css2?family=...&display=swap"
+  const FONT_LINK_ID = "vantage-slide-font-june"  // デッキごとに違う id にする
+  if (typeof document !== "undefined" && !document.getElementById(FONT_LINK_ID)) {
+    const link = document.createElement("link")
+    link.id = FONT_LINK_ID
+    link.rel = "stylesheet"
+    link.href = FONT_HREF
+    document.head.appendChild(link)
+  }
+  ```
+
+- **実際に使うウェイトだけを列挙する。** 余分な 1 ウェイトが `@font-face` の数を倍にします。
+
+## webfont と pptx 書き出し —— ここが壊れやすい
+
+pptx 書き出しは、スライドを SVG の `foreignObject` の中でラスタライズします。この隔離された
+描画コンテキストでは:
+
+- **ローカルにインストールされたフォントはファミリ名で解決されます。** システムスタックなら
+  埋め込みは 1 バイトも要りません。既定のままなら何もしなくてよい、ということです
+- **webfont は data URL としてインライン化されていなければ使えません。** 書き出しは
+  `getFontEmbedCSS` で自動的にインライン化しますが、それには 2 つの条件があります:
+  - **同一オリジンか CORS が有効**であること（Google Fonts は CORS 有効）
+  - **サブセットしてあること。** 日本語の webfont は致命的です —— Noto Sans JP のフルセットは
+    100 を超える `unicode-range` の face を持ち、全部を base64 化しようとして書き出しが
+    タイムアウトするか、文字が豆腐になります。デッキの文字が固定なら Google Fonts の URL に
+    **`&text=<使う文字>`** を付けて、単一 face の小さなサブセットを要求してください
+
+**判断の目安**: 日本語のデッキで pptx を配る予定があるなら、**システムスタックのままにする**のが
+最も確実です。ブランドフォントが要件なら `&text=` のサブセットにすること。

package/base-template/.squadbase/skills/vantage-slide/references/transitions.md

@@ -0,0 +1,196 @@
+# ページ間トランジション（`SlideTransition`）
+
+スライドが切り替わるときの enter / exit アニメーションです。**既定はありません** ——
+宣言しない限りページはスナップで入れ替わり、そのスナップも十分に上品な既定です。
+動きが何かを足すときだけ opt-in してください。
+
+`prefers-reduced-motion: reduce` は自動で尊重されます。フォールバックを書く必要はありません。
+
+（2 枚にまたがる同一要素を動かす「Magic Move」は `morph.md`。この契約の上に載っています。）
+
+## 契約
+
+トランジションは `<Slide transition={...}>` に付けます。**入ってくる側が勝ちます**:
+A → B の移動では B の `transition` が使われ、その `exit` が A で、`enter` が B で再生されます。
+B → A と戻るときは A の `transition` が使われるので、**両方向で動かしたいなら両方のスライドに
+同じオブジェクトを渡します**。
+
+```tsx
+import { Slide, SlideDeck, type SlideTransition } from "@squadbase/vantage/slide"
+
+const RISE: SlideTransition = { /* … */ }
+
+<SlideDeck>
+  <Slide>…</Slide>
+  <Slide transition={RISE}>…</Slide>
+</SlideDeck>
+```
+
+```ts
+type TransitionPhase = {
+  keyframes: Keyframe[] | PropertyIndexedKeyframes  // WAAPI のキーフレーム
+  duration?: number   // ms（省略時は上位の duration）
+  easing?: string     // CSS easing
+  delay?: number      // ms —— exit と enter を重ねるのに使う
+}
+type SlideTransition = {
+  duration: number                     // 上位のフォールバック
+  easing?: string
+  enter?: TransitionPhase              // 入ってくる側で再生
+  exit?: TransitionPhase               // 出ていく側で再生
+  morph?: boolean | MorphTransition    // 共有要素のモーフ → morph.md
+}
+```
+
+ラッパーには `--slide-dir`（前進 `1` / 後退 `-1`）と `data-slide-dir`（`"forward"` / `"backward"`）が
+出るので、JS のコールバック無しに 1 つのキーフレームで方向を反転できます。
+
+## 設計原則（ここは崩さない）
+
+「PowerPoint で作りました」と最も大きく告げるのは、1 つのデッキに 6 種類のトランジションがあることです。
+節度がリズムを作ります。
+
+- **DNA を 1 つ選び、デッキ全体で保つ。** 同じ duration 帯、同じ easing の組、同じ out → in のずらし方。
+  変えてよいのは**どのプロパティに小さな一押しを乗せるか**だけ —— Y、X、opacity、scale、blur
+- **duration: 140–280ms。** exit 140–180ms、enter 200–280ms、enter を 80ms ほど遅らせて重ねる。
+  350ms を超えると動画編集の領域で、本当の状態変化のために取っておく
+- **振れ幅の上限: 12px か 3% スケール。** 6px の Y 上昇は「次の考え」に読める。1920px の translateX は
+  「別の書類」に読める。上質なツールは、気づく分だけしか動かさない
+- **opacity は常に混ぜる。** transform だけのトランジションは硬く、opacity だけのものは最も安全な既定
+- **easing: exit は ease-in、enter は ease-out。** 出るとき `cubic-bezier(0.4, 0, 1, 1)`、
+  入るとき `cubic-bezier(0, 0, 0.2, 1)`。`linear` は使わない（スライドショーに見える）。
+  対称な ease-in-out は状態が繋がるモーフのために取っておく
+
+## 上品な family —— 6 つ、1 つの DNA
+
+ここから選んでください。1 つをデッキの標準にし、必要ならヒーロー / 表紙用に 2 つ目、
+本当の章の切れ目に 3 つ目を取っておきます。
+
+```tsx
+const EASE_OUT = "cubic-bezier(0, 0, 0.2, 1)"
+const EASE_IN = "cubic-bezier(0.4, 0, 1, 1)"
+
+// RISE —— 標準の静けさ。Y に 6px。デッキの既定にする
+const RISE: SlideTransition = {
+  duration: 200,
+  exit: {
+    duration: 140, easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: "translateY(0)" },
+      { opacity: 0, transform: "translateY(-4px)" },
+    ],
+  },
+  enter: {
+    duration: 200, delay: 80, easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: "translateY(6px)" },
+      { opacity: 1, transform: "translateY(0)" },
+    ],
+  },
+}
+
+// DISSOLVE —— opacity だけ。最も静か
+const DISSOLVE: SlideTransition = {
+  duration: 240,
+  exit: { duration: 200, easing: EASE_IN, keyframes: [{ opacity: 1 }, { opacity: 0 }] },
+  enter: { duration: 240, delay: 40, easing: EASE_OUT, keyframes: [{ opacity: 0 }, { opacity: 1 }] },
+}
+
+// SETTLE —— 表紙向き。上昇 + enter だけにわずかな blur
+const SETTLE: SlideTransition = {
+  duration: 280,
+  exit: {
+    duration: 160, easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: "translateY(0)" },
+      { opacity: 0, transform: "translateY(-6px)" },
+    ],
+  },
+  enter: {
+    duration: 280, delay: 100, easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: "translateY(12px)", filter: "blur(4px)" },
+      { opacity: 1, transform: "translateY(0)", filter: "blur(0)" },
+    ],
+  },
+}
+
+// BLOOM —— scale 0.97 → 1、移動なし。その場で像を結ぶ
+const BLOOM: SlideTransition = {
+  duration: 240,
+  exit: {
+    duration: 160, easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: "scale(1)" },
+      { opacity: 0, transform: "scale(1.01)" },
+    ],
+  },
+  enter: {
+    duration: 240, delay: 80, easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: "scale(0.97)" },
+      { opacity: 1, transform: "scale(1)" },
+    ],
+  },
+}
+
+// FALL —— RISE の鏡像。上から降りてくる
+const FALL: SlideTransition = {
+  duration: 200,
+  exit: {
+    duration: 140, easing: EASE_IN,
+    keyframes: [
+      { opacity: 1, transform: "translateY(0)" },
+      { opacity: 0, transform: "translateY(4px)" },
+    ],
+  },
+  enter: {
+    duration: 200, delay: 80, easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: "translateY(-6px)" },
+      { opacity: 1, transform: "translateY(0)" },
+    ],
+  },
+}
+
+// BREATH —— 章の切れ目。完全に消してから 120ms 置いて入る
+// 本当の区切りにだけ、デッキ 1 本で 1〜2 回まで
+const BREATH: SlideTransition = {
+  duration: 460,
+  exit: { duration: 180, easing: EASE_IN, keyframes: [{ opacity: 1 }, { opacity: 0 }] },
+  enter: {
+    duration: 240, delay: 300, easing: EASE_OUT,
+    keyframes: [
+      { opacity: 0, transform: "translateY(8px)" },
+      { opacity: 1, transform: "translateY(0)" },
+    ],
+  },
+}
+```
+
+6 つは同じ DNA を共有していて、小さな一押しをどのプロパティに乗せるかだけが違います。
+読み手には変化に見え、それでいて 1 つの手つきに読めます。
+
+## 方向を意識したキーフレーム（控えめに）
+
+上品なツールの多くは後退時に鏡像化しません。本当に必要なとき（横に流れるスライドを逆再生したい等）
+だけ `--slide-dir` を `calc()` の中で使います:
+
+```tsx
+{ transform: "translateX(calc(var(--slide-dir, 1) * 8px))" },
+{ transform: "translateX(0)" },
+```
+
+毎回これに手が伸びるなら、たぶん設計しすぎです。前進 = 後退の方が洗練された既定。
+
+## アンチパターン
+
+- ❌ 6 ページに 6 種類のトランジション —— 最も大きな「PowerPoint 感」の合図
+- ❌ `translateX(100%)` の横スライド —— iOS のモーダルや PowerPoint の Push であって、スライドの切り替えではない
+- ❌ 強いスケールのポップ（`0.85 → 1`）+ blur —— ライトボックスの語彙で、何かに「ズームイン」する意味になる
+- ❌ `clip-path: inset(…)` のワイプ —— After Effects の語彙。芝居がかる
+- ❌ 両方のレイヤーに同時に blur —— 視覚的な濁り。目が焦点を結べない
+- ❌ 通常の切り替えで 350ms を超える duration —— 間延びする
+- ❌ 12px / 3% を超える移動 —— 連続ではなく断絶に読める
+- ❌ `linear` easing —— プロダクトではなくスライドショーに見える
+- ❌ とりあえずトランジションを宣言する。**理由が無いなら書かない。** スナップで十分

package/base-template/AGENTS.md

@@ -93,7 +93,7 @@ root/
 | `@squadbase/vantage/router` | `Link`・`Outlet`・`useParams`・`useSearch`・`useNavigate`・`redirect`・`notFound`・`useRoutes`・`useCurrentRoute`・`useSearchParam`・`useSearchState` |
 | `@squadbase/vantage/query` | `useApiQuery`・`useApiMutation`・`apiJson`・`apiFetch`・`apiUrl`・`ApiError`、ほか `useQuery`/`useMutation` など TanStack Query の再エクスポート |
 | `@squadbase/vantage/ui` | shadcn/ui(Base UI バリアント)プリミティブ(`Button`・`Loading`・`ErrorState`・`Empty` ほか) |
-| `@squadbase/vantage/components` | 複合パーツ(`PageShell`・`DashboardCardPreset`・`DataTablePreset`・`EChart` ほか) |
+| `@squadbase/vantage/components` | 複合パーツ(`PageShell`・`DashboardCardPreset`・`DataTablePreset`、型付きチャート `LineChart`・`BarChart`・`AreaChart`・`DonutChart`・`BarList` ほか、`EChart`) |
 | `@squadbase/vantage/table` | `FilePageView`・`TableViewer`(データファイルページの表ビューア) |
 | `@squadbase/vantage/slide` | `SlideDeck`・`Slide`・`Steps`・`Step`・`MorphElement`・`useSlideNumber`・`useIsActiveSlide`(スライド専用。1920×1080 の固定キャンバス) |
 | `@squadbase/vantage/doc` | `Document`(ドキュメント専用。中の素の HTML 要素に見出し・表などのスタイルが当たる) |
@@ -137,6 +137,15 @@ root/
 | `.xlsx` ページ | `agents/xlsx.md` |
 | `.csv` ページ | `agents/csv.md` |
 
+**ページになるのは `.tsx` / `.jsx`(`.slide.tsx`・`.doc.tsx` を含む)・`.csv`・`.xlsx` だけ。**
+
+- `.xls`・`.xlsm`・`.xlsb`・`.ods`・`.tsv`・`.numbers`・`.parquet` はルートにならず、404 にもならない。
+  `vantage check` の `UNSUPPORTED_PAGE_FILE` 警告だけが知らせる。`.xlsx` / `.csv` に変換して置く
+- `.md`・`.json`・`.txt` は何も言わずに無視される。Markdown を見せたいときは `.tsx` のページで
+  `MarkdownRenderer`(`@squadbase/vantage/markdown`)に渡す
+- `.csv` / `.xlsx` はブラウザでパースする。25MB を超えるとそのページにエラーが出る
+  (`FILE_PAGE_TOO_LARGE` 警告)。20 万行を超えるシートは先頭 20 万行だけが表示される
+
 ## 環境変数
 
 - **クライアントで読めるのは `import.meta.env.PUBLIC_*` と `MODE`/`DEV`/`PROD`/`SSR`/`BASE_URL`
@@ -399,7 +408,7 @@ lockfile は `bun.lock`)。Squadbase のサンドボックスは bun と依存
   - 書き込む場所: `src/<slug>.doc.tsx`
   - ページ: あり
   - 作り方: `src/<slug>.doc.tsx` に `<Document>` を返すページを置く(`@squadbase/vantage/doc`。
-    ルートは `.doc` を除いた `/<slug>`)。数値はコードに直接書き、チャートは `EChart` を文中に置く。
+    ルートは `.doc` を除いた `/<slug>`)。数値はコードに直接書き、チャートは `@squadbase/vantage/components` のチャート部品を文中に置く。
     書く前に `agents/doc.md` を読む。
 - **オートメーション** — 決まった時刻に集計・通知・定期レポートを回したいとき、しきい値で
   アラートしたいとき。
@@ -408,6 +417,12 @@ lockfile は `bun.lock`)。Squadbase のサンドボックスは bun と依存
   - 作り方: `automations/<名前>/automation.yml` に定義し、処理のコードは `pipelines/` に置く。
     書く前に Automation のガイド(`readAutomationGuide`)を読む。
 
+CSV / Excel(`.csv` / `.xlsx`)は上の項目とは別で、書いて作るものではない。受け取ったファイルを
+`src/` に置くだけで表として読めるページになる(`src/data/june.xlsx` → `/data/june`。置く前に
+`agents/csv.md` / `agents/xlsx.md` を読む)。値だけが表示され、数式・書式は再現されない。25MB を
+超えるとエラー、20 万行を超えると先頭 20 万行だけが出る。`.xls`・`.ods`・`.tsv` などはページにならない
+(`vantage check` の `UNSUPPORTED_PAGE_FILE` 警告)。
+
 ## 表示領域に安定 ID を付ける(`data-sq-ref`)
 
 Squadbase のチャットは、回答の根拠になったグラフ・表・KPI カードを
@@ -427,8 +442,9 @@ Squadbase のチャットは、回答の根拠になったグラフ・表・KPI
 ### 追加の不変条件
 
 - **意味のまとまった表示領域(グラフ・表・KPI カードなど)のルート要素に付ける。** 通常は
-  `DashboardCard` / `DashboardCardPreset` のように props を DOM に流す部品。`EChart` / `DataTable` /
-  `SectionHeader` は付けた属性を DOM に流さないので、それらを包むカード(または `div`)に付ける。
+  `DashboardCard` / `DashboardCardPreset` のように props を DOM に流す部品。`EChart` と ECharts で描く
+  チャート部品(`LineChart` / `BarChart` / `AreaChart` / `DonutChart`)・`DataTable` / `SectionHeader` は
+  付けた属性を DOM に流さないので、それらを包むカード(または `div`)に付ける。
 - **値の形式は `^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$`**(ASCII の英数字・ハイフン・アンダースコア、先頭は英数字、
   100 文字以内)。これ以外の値はリンクから開けない。推奨は意味を表す小文字 kebab-case の名前
   (例: `revenue-trend`, `churn-by-segment`)。表示順・ソース上の位置・index・連番から作らない。

package/base-template/agents/csv.md

@@ -27,6 +27,7 @@
   ```
 - 数式・グラフ・セル書式といった概念は csv には無いので、値がそのまま読めます。ブラウザで
   パースするので 25MB を超えるファイルはそのページにエラーが出ます —— 大きいデータは
-  `server/api/` から配って `DataTable` で描いてください
+  `server/api/` から配って `DataTable` で描いてください。20 万行を超えると先頭
+  20 万行だけが表示されます(残りはダウンロードして見る)
 - **ビューアの無い拡張子(`.tsv` など)はルートになりません。** `vantage check` の
   `UNSUPPORTED_PAGE_FILE` 警告が知らせます

package/base-template/agents/doc.md

@@ -12,7 +12,7 @@
 
 ```tsx
 import { definePage } from "@squadbase/vantage"
-import { EChart } from "@squadbase/vantage/components"
+import { BarChart } from "@squadbase/vantage/components"
 import { Document } from "@squadbase/vantage/doc"
 
 export const page = definePage({ title: "6月度サマリー", navLabel: "6月度サマリー" })
@@ -23,7 +23,7 @@ export default function JuneSummary() {
       <p>6月の売上は <strong>5,250 万円</strong>で、目標を 5% 上回りました。</p>
       <h2>週次の売上</h2>
       <figure>
-        <EChart option={option} height={280} ariaLabel="6月の週次売上" />
+        <BarChart data={weekly} index="week" categories={["売上"]} height={280} ariaLabel="6月の週次売上" />
         <figcaption>第4週はキャンペーン初週</figcaption>
       </figure>
       <table>…</table>
@@ -42,7 +42,8 @@ export default function JuneSummary() {
   見た目を変えたいときはユーティリティを並べず、下の `--doc-*` を変えます。
 - **数値はコードに直接書く。** ドキュメントは書いた時点の内容を残すページです。
   `useApiQuery` などで読み込むと、開くたびに値が変わります。
-- **チャートは `EChart`(`@squadbase/vantage/components`)を文中に置く。** `figure` で囲めば
+- **チャートは型付きチャート(`BarChart`・`LineChart` など。`@squadbase/vantage/components`)を
+  文中に置く**(選び方は `agents/page.md` の「グラフはまず型付きチャートで描く」)。`figure` で囲めば
   `figcaption` がキャプションになります。
 - **PDF の保存ボタンは作らない。** `<Document>` が右下に PDF 保存のボタンを出し、印刷時は
   本文だけをライトの配色で出します。

package/base-template/agents/page.md

@@ -26,8 +26,8 @@
   },
   "dependencies": {
     "@squadbase/vantage": "^0.5.0",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7"
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
   }
 }
 ```
@@ -164,17 +164,31 @@ refetchOnWindowFocus false・networkMode "always")。挙動を変えたいとき
 ## 組み込み UI / コンポーネントの入口
 
 - **プリミティブ**は `@squadbase/vantage/ui` から import する(`Button`・`Loading`・
-  `ErrorState`・`Empty`・`Select`・`Checkbox` ほか)。
+  `ErrorState`・`Empty`・`Select`・`Checkbox`・`RadioGroup`・`Field`・`Combobox`・`Pagination`・
+  `Avatar`・`Kbd`・`HoverCard`・`AlertDialog`・`Drawer`・`Toaster` + `toast.add()` ほか)。
 - **複合パーツ**は `@squadbase/vantage/components` から(`PageShell`・`DashboardCardPreset`・
-  `DataTablePreset`・`EChart` ほか)。
+  `DataTablePreset`・型付きチャート(下の「グラフ」)・`EChart` ほか)。
 - **どの名前が import 可能か / props の詳細は `vantage docs` で引く。** ガイドとコンポーネント
   リファレンスはパッケージに同梱されていて、オフラインでも読める(→ `AGENTS.md` の
   「ドキュメントを引く」)。**名前が分からないとき**はやりたいことで `vantage search` する
   (→ 同節)。
-- **UI は import して使うのが既定。取り出す(eject)必要はない。** `vantage add ui|block` は
-  ソースを手元にコピーして**改造したいとき専用**のコマンドで、取り出せるのは
-  `ui: data-table` と `block: sales-overview` の 2 つだけ。それ以外の名前は import 専用で
-  `add` の対象ではない(未知名で実行すると候補が一覧表示される)。
+- **UI は import して使うのが既定。取り出す(eject)必要はない。** `vantage add ui <name>` は
+  ソースを手元にコピーして**改造したいとき専用**のコマンド。`/ui` のプリミティブも
+  `/components` の複合パーツも全部取り出せる(名前は kebab-case: `add ui bar-chart`。
+  ブロックは `add block sales-overview`。未知名で実行すると候補が一覧表示される)。
+
+### グラフはまず型付きチャートで描く
+
+- 推移は `LineChart` / `AreaChart`、比較は `BarChart`、構成比は `DonutChart`。`data`(行の配列)・
+  `index`(x 軸の列)・`categories`(系列の列)を渡すだけで、option は書かない
+  (`DonutChart` は `category` / `value`)。
+- 上位 N 件は `BarList`、判定帯や予算消化は `CategoryBar`、達成率は `ProgressCircle`、
+  日ごとの状態は `Tracker`。
+- `EChart` + `EChartsOption` は、二軸・散布図・ヒートマップ・注釈線など型付きチャートの props で
+  表せないときだけ使う。
+- 色は省略してテーマトークンに任せる。指定するなら `"chart-1"`〜`"chart-5"` か
+  `"var(--destructive)"` などの CSS 色。hex の直書きや Tailwind クラスは使わない。
+- 数値の書式(`¥`・`%`・桁区切り)は `valueFormatter` に渡す。
 
 ### ダークモードは opt-in
 

package/base-template/agents/xlsx.md

@@ -28,6 +28,7 @@
 - **複数シートに対応**しています。シートのタブは下端に並び、切り替えて閲覧できます。
 - 数式・グラフ・セル書式は再現されません(値として読めれば十分、という設計)。ブラウザでパースするので
   25MB を超えるファイルはそのページにエラーが出ます —— 大きいデータは `server/api/` から配って
-  `DataTable` で描いてください
+  `DataTable` で描いてください。20 万行を超えると先頭
+  20 万行だけが表示されます(残りはダウンロードして見る)
 - **ビューアの無い拡張子(`.xls`・`.ods` など)はルートになりません。** `vantage check` の
   `UNSUPPORTED_PAGE_FILE` 警告が知らせます