@squadbase/vantage-template 0.1.1-dev1.2be5c44 → 0.1.1-dev1.39049f4

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

@@ -0,0 +1,57 @@
+# 段階表示（`<Steps>` / `<Step>`）
+
+一度に全部見せる代わりに、1 拍ずつ開いていきます。後から出す部分を `<Step>` で、そのまとまりを
+`<Steps>` で包む。`→` を押すたびに次の `<Step>` が現れ、最後の 1 つの後の `→` で次のスライドへ
+進みます。`←` は直前の 1 つを畳みます。**順序そのものが主張になっている**ときに使う道具です
+—— 前提 → 帰結 → 転換のように、聴衆が話し手の速さで読むようにするためのもの。
+
+```tsx
+import { Step, Steps } from "@squadbase/vantage/slide"
+
+<Steps>
+  <Step><p style={ROW}>聴衆は話し手より速く読む。</p></Step>
+  <Step><p style={ROW}>全部を一度に出すと先読みされる。</p></Step>
+  <Step><p style={ROW}>時間差で出すと注意を配れる。</p></Step>
+</Steps>
+```
+
+## 規則
+
+- **`<Step>` は `<Steps>` の直接の子でなければならない。** 深くネストした（あるいは `<Steps>` の
+  外に置いた）`<Step>` は**最初から全部表示された状態**で描かれ、何も遅延しません。静かに効かない
+  ので気づきにくい。
+- **`<Step>` でない子はすぐ表示される。** 見出しや導入の段落を `<Steps>` の中にプレーンな要素として
+  置けば最初から見えます。「見出しは常に、本文は順に」のパターン:
+
+  ```tsx
+  <Steps>
+    <h2>全部が待つ必要はない。</h2>{/* 最初から見える */}
+    <Step><p>まず状況を置いて…</p></Step>
+    <Step><p>次に帰結を重ねる…</p></Step>
+  </Steps>
+  ```
+
+- **1 ページに複数の `<Steps>` があるとマウント順に連なる。** 最初のまとまりが全部開いてから
+  次が始まり、`←` は逆順に畳みます。左の列 → 右の列の順に組み上げる 2 カラムは、各列が自分の
+  `<Steps>` を持てばそのまま実現できます。
+- **入り方で初期状態が変わる —— 同じ中身、2 つのリズム。** 前のスライドから `→` で進んで入ると
+  空から積み上がります。`?p=` のリンクで直接入る、あるいは後ろのスライドから戻ってくると、
+  **全部開いた完成形**で表示されます。**どちらでも読めるように設計すること** —— 直リンクで開いた
+  ときに白紙に見えるページは失敗です。
+- **`<Step>` は `duration` ミリ秒（既定 180）でフェードインする。** `<Step duration={...}>` で変えられます。
+  `prefers-reduced-motion: reduce` は自動で即時カットになるので、フォールバックを書く必要はありません。
+- **pptx 書き出しでは全部開いた状態で出ます。** 書き出しは `<Steps>` のホストを持たないインスタンスで
+  描かれるため。段階表示は画面での演出であって、配布物の状態ではありません。
+
+## いつ使うか
+
+順序が主張になっているとき —— 最後の項目が落ちどころになる箇条書き、結論への積み上げ、
+before / after。**全ページの中身を反射的に `<Step>` で包まないこと**: 一目で受け取ってほしい
+ページ（ヒーロータイトル、引用 1 つ、図）は、丸ごと見せた方が強い。段階表示は演出ではなく
+タイミングの道具で、トランジションと同じ節度が要ります。
+
+## アンチパターン
+
+- ❌ 全ページの中身を反射的に `<Step>` で包む。一目で伝わるページは丸ごと見せる方が強い
+- ❌ `<Steps>` の直接の子でない `<Step>`（深いネスト、`<Steps>` 無し）。全開で描かれ、何も遅延しない
+- ❌ 直リンクで開くと白紙に見えるページ。`?p=` で入ると全開になることを前提に設計する

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

@@ -7,8 +7,8 @@
 > このファイルと `agents/*.md` は、いずれも **Vantage フレームワークが所有する正本**の
 > コピーです。手で書き換えても、`vantage upgrade` を実行するとフレームワーク同梱の正本から
 > 再同期されて上書きされます。アプリ固有のメモは別ファイル(例: `README.md`)に書いてください。
-> 例外はプロジェクトルートの `DESIGN.md` で、これは**ユーザーが所有**します(`vantage upgrade` も
-> `vantage add agents` も触らない。→「デザインの意図(DESIGN.md)」)。
+> 例外はプロジェクトルートの任意の `DESIGN.md` で、これは**ユーザーが所有**します(`vantage upgrade` も
+> `vantage add agents` も触らない。→「見た目の規約」)。
 >
 > 手順を伴う踏み込んだワークフローは、同梱の Claude Code Skill に分かれています。このファイルは
 > 「地図」、`agents/*.md` は「種類ごとの静的リファレンス」、Skill は「手順書」という役割分担です。
@@ -47,6 +47,8 @@ UI キット・開発サーバー・API サーバー・ビルドはすべて Van
 - **`definePage` の値はリテラルで書く。** title/description/navLabel はビルド時に静的抽出される
   ため、変数・関数呼び出し・テンプレート補間は使わない。`page` エクスポートはランタイムでは
   読まれない。
+- **アプリの表示言語は、ルート `_layout.tsx` の `export const lang = "ja"`(リテラル)で指定する。**
+  `<html lang>` になり、日本語の文節改行とスライドの文言切り替えに効く。未指定は `"en"`。
 
 ## ディレクトリ構造(ページをどこに置くか)
 
@@ -93,13 +95,25 @@ 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`、KPI の `KpiCard`・`Delta`、型付きチャート `LineChart`・`BarChart`・`AreaChart`・`DonutChart`・`BarList` ほか、`EChart`、書式の `formatValue`) |
 | `@squadbase/vantage/table` | `FilePageView`・`TableViewer`(データファイルページの表ビューア) |
-| `@squadbase/vantage/slide` | `SlideDeck`・`Slide`・`Steps`・`Step`・`MorphElement`・`useSlideNumber`・`useIsActiveSlide`(スライド専用。1920×1080 の固定キャンバス) |
-| `@squadbase/vantage/doc` | `Document`(ドキュメント専用。中の素の HTML 要素に見出し・表などのスタイルが当たる) |
+| `@squadbase/vantage/slide` | `SlideDeck`・`Slide`・`Steps`・`Step`・`MorphElement`・`useSlideNumber`・`useIsActiveSlide`、1 枚分の block `SlideCover`・`SlideExecSummary`・`SlideKpiHero`・`SlideKpiGrid`・`SlideChartInsight`・`SlideScorecardTable`・`SlideNextActions`・`SlideSection`・`SlideComparison`・`SlideChartFull`、手書きの 1 枚に使う部品 `SlideHeading`・`SlideSourceLine`・`SlideColumns`・`SlideColumn`・`DeltaText`(スライド専用。1920×1080 の固定キャンバス) |
+| `@squadbase/vantage/doc` | `Document`、ドキュメント用の block `DocReportHeader`・`DocExecutiveSummary`・`DocKpiScorecard`・`DocFigure`・`DocDataTable`・`DocCallout`・`DocKeyFindings`・`DocActionItems`・`DocNotesAndSources`、部品 `DeltaText`(ドキュメント専用。中の素の HTML 要素に見出し・表などのスタイルが当たる) |
 | `@squadbase/vantage/markdown` | `MarkdownRenderer`(Shiki を隔離するための専用サブパス) |
 | `@squadbase/vantage/server` | `ApiContext`・`ApiHandler`・`HttpError`・`isHttpError`・`json`(server/ 側でのみ使う) |
 
+**KPI は `KpiCard`、増減は `Delta`(`comparison` を渡し、下がって良い指標は `betterWhen="down"`)。** 向き・率・色は値から計算
+されるので手で渡さない。`TrendIndicator` は非推奨(`direction` を手で渡すので値と食い違いうる)。props は
+`vantage docs kpi-card` / `vantage docs delta` を引く。
+
+```tsx
+import { KpiCard, Delta } from "@squadbase/vantage/components";
+
+<KpiCard label="売上" value={48_200_000} format="currency"
+  comparison={{ previous: 42_900_000, vs: "prior-period" }} />
+<Delta value={0.021} comparison={{ previous: 0.026, vs: "prior-period" }} polarity="lower-is-better" />
+```
+
 ## モードは 2 つ、切り替えるのは `server/` の有無だけ
 
 `server/` ディレクトリがあれば **fullstack**、無ければ **SPA**。`vantage-manifest.json` の
@@ -111,17 +125,30 @@ root/
 - `server/` が**無い** → 外部 API を直接叩くなら `useQuery`(→ `agents/page.md`)。自前の API が
   要るようになったら `server/api/*.ts` を足すだけでよい(設定変更は不要)。
 
-## デザインの意図(DESIGN.md)
+## 見た目の規約
+
+色・書体・角丸などの**値と色の割り当ては、テーマ(`styles.css` の `/* theme: <name> */` マーカー以降の
+上書き)だけが持つ。** ここには値を書かず、使い分けの規則だけを置く。UI(ページ・スライド・
+コンポーネント)はこの規則に従い、色は必ずトークンで指定する(色コード・素のパレットクラスは書かない)。
 
-プロジェクトルートに `DESIGN.md` があれば、**UI(ページ・スライド・コンポーネント)を書く前に
-読む。** 色・チャート・書体・レイアウトの使い分けがトークン名で書いてあるので、それに従って
-トークンで書く(値は `styles.css` にあり、`DESIGN.md` には色コードを書かない)。
+- **意味トークン:** 良い = `positive`、悪い = `negative`、注意 = `warning`、情報 = `info`、
+  中立 = `neutral`。系列色は `chart-1`〜`chart-5` を番号順に使う(5 系列まで。超えるなら「その他」に
+  まとめる)。増減の良否は指標の性質(コスト減・解約率減は良い)で決めて
+  positive / negative に分け(`KpiCard` / `Delta` の `betterWhen`。下がって良い指標は `betterWhen="down"`)、向きは ▲▼ や符号で表す。
+- **レイアウト:** 内容はカードで包む。順序は KPI → チャート → 表。値が 1 つなら KPI にする
+  (1 本の棒グラフにしない)。強調は 1 画面(スライドは 1 枚)に 1 か所。数値には単位と比較対象を添える。
+- **Do:** トークンで色を指定する / 色の意味をアプリ全体でそろえる / チャートのタイトルに結論を書く。
+- **Don't:** 色コードや素のパレットクラスを書く / `dark:` を並べる / 3D・装飾目的のグラデーション・
+  円グラフの多用 / 同じチャートで `negative` を普通の系列色に使う。
+- スライド固有の規則は `agents/slide.md`。
 
-- **会話中の指示は `DESIGN.md` より優先する。** 同じ指示が繰り返されたら、`DESIGN.md` への
-  反映をユーザーに提案する。
-- **「色を変えて」「ブランドに合わせて」などデザイン全体の変更は、ファイルごとに直さない。**
-  Skill `vantage-design` の手順で `DESIGN.md` と `styles.css` をまとめて更新する。
-- `DESIGN.md` はユーザーの持ち物。`vantage upgrade` は書き換えない。
+**任意の `DESIGN.md`:** プロジェクトルートにあれば読んで従う(密度・スライドの見出し方針・
+ブランド素材などユーザー固有の意図)。AGENTS.md の規則に加えて従うが、**色の割り当てはテーマを優先**
+する。新規には作らない。ユーザーの持ち物で、`vantage upgrade` は書き換えも削除もしない。
+
+**デザイン変更の依頼**(「もっと落ち着いた色に」「ブランドに合わせて」など)は、ファイルごとに
+直さず、テーマの切り替えかスタイルシートの上書きで完結させる。`DESIGN.md` には記録しない。今のテーマ名は
+`styles.css` の `/* theme: <name> */` マーカーから読む。手順は Skill `vantage-design`。
 
 ## 何を書くか → どのファイルを読むか
 
@@ -137,6 +164,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`
@@ -189,7 +225,7 @@ body・レスポンスの status と形)まで出る。`vantage check --json` /
 - **`vantage-app`** — アプリを一から作る / 構成を広げるときの進め方と検証の順序
 - **`vantage-add-feature`** — 既存アプリに page / api / ui を 1 つ足す定型
 - **`vantage-slide`** — `.slide.tsx` でスライドデッキを書く(キャンバスの予算・段階表示・pptx 書き出し)
-- **`vantage-design`** — `DESIGN.md` と `styles.css` をまとめて作る / 直す(配色・書体・ブランド合わせ)
+- **`vantage-design`** — テーマの切り替え・`styles.css` の上書きで見た目を直す(配色・書体・ブランド合わせ)
 - **`vantage-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
 - **`project-storage`** — Squadbase の Project Storage(アップロード済みファイル)をブラウザから読み書きする
 
@@ -224,7 +260,7 @@ vantage add skill --all --dir .claude/skills   # 置き場所を指定(既定は
 > `vantage upgrade` はこのファイルをフレームワーク同梱の正本で丸ごと上書きするため、
 > このセクションは消えます。消えたら squadbase-monorepo の
 > `packages/vantage-template/agents/vantage/` から貼り直してください
-> (リポジトリ側では `npm run agents` が正本と結合して再生成します)。
+> (リポジトリ側では `pnpm run agents` が正本と結合して再生成します)。
 
 ## Squadbase の Connection / Query からデータを読む
 
@@ -302,6 +338,34 @@ const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
 })
 ```
 
+### 生の応答から行を取り出す(`noUncheckedIndexedAccess`)
+
+テンプレートの `tsconfig.json` は `noUncheckedIndexedAccess: true`。**配列の添字はすべて
+`T | undefined`** なので、HTTP Query が通す上流の生の応答(GA4 の `rows[].metricValues[]` など)を
+`row.metricValues[0].value` と書くと `Object is possibly 'undefined'.` で落ちる。書く前に添字
+アクセスを頭の中で型検査し、応答の型と行の変換関数を先に決めて `?.` と `??` で取り出す:
+
+```ts
+type Ga4Row = {
+  dimensionValues?: { value?: string }[]
+  metricValues?: { value?: string }[]
+}
+type SessionsDaily = { date: string; sessions: number; pageViews: number }
+
+const toSessionsDaily = (row: Ga4Row): SessionsDaily => ({
+  date: row.dimensionValues?.[0]?.value ?? "",
+  sessions: Number(row.metricValues?.[0]?.value ?? "0"),
+  pageViews: Number(row.metricValues?.[1]?.value ?? "0"),
+})
+
+const report = (await res.json()) as { rows?: Ga4Row[] }
+return Response.json((report.rows ?? []).map(toSessionsDaily))
+```
+
+- 値が欠けた行を落としたいときは `if (!date) throw new HttpError(502, …)` ではなく、変換後に
+  `.filter((r) => r.date !== "")` で除く。`date!` のような非 null 断言で黙らせない。
+- SQL Query の `rows` も同じ。`rows[0]` を使うなら `const first = rows[0]; if (!first) …` で先に絞る。
+
 ## 構築中の一時的なエラーを「進行中」に見せる(`components/build-recovery.tsx`)
 
 ページを書いている途中は、ファイルが書き終わる順番の都合で一瞬だけページが throw する
@@ -314,6 +378,10 @@ const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
 `components/build-recovery.tsx` の `BuildRecovery` が、その画面を DOM から検知して
 `Working on it…` 表示を被せ、dev では 1.2 秒待ってから自動でリロードして復帰させる
 (上限 3 回。使い切ったら「再読み込み」の案内に降格し、無事に描けたら残数が戻る)。
+**ただし `window.__VANTAGE_DRAFT__?.active` が `true` の間(AI の書きかけのファイルを下書きとして
+プレビューに出している間)は、覆わず・リロードもしない。** 下書き中の描画エラーはフレームワークが
+直前に通った版へ戻すので、ここで覆うとその版の表示まで隠れ、リロードすると下書きの表示ごと消える。
+下書きが終わった時点でエラー画面が残っていれば、通常どおり覆う。
 降格した画面にはエラー本文をそのまま出し、`Copy log` でコピーできるようにしてある —
 自力で直らないときに本文をそのまま貼り戻してもらうため。
 `_error.tsx` も同じ `RecoveringState` を描くので、ルートレイアウトが throw したときの
@@ -349,3 +417,121 @@ lockfile は `bun.lock`)。Squadbase のサンドボックスは bun と依存
   `bun install` を一度走らせて `bun.lock` を追従させ、両方を同じコミットに入れる。
 - スクリプトは `bun run <script>`(`bun run dev` / `bun run build` / `bun run check` /
   `bun run routes`)。`npm run <script>` でも動くが、install に npm を使わないこと。
+- **公開から 48 時間未満の版は入らない。** `bunfig.toml` の `minimumReleaseAge`(サプライチェーン対策)で
+  弾かれる。`bun add` / `bun install` が「バージョンが見つからない」で落ちたら、直近の版を避けて
+  少し前の版を指定する。`bunfig.toml` の設定を緩めたり `@squadbase/*` 以外の除外を足したりしない。
+
+## このアプリで作れるもの
+
+ユーザーの目的に合わせて、どの形にするかを選ぶ。ここに書かれていない形は約束しない。
+
+- **ダッシュボード** — 数字を繰り返し見に来て、変化に気づきたいとき。指標と推移・内訳を 1 画面に
+  置き、`server/api/` で実データを取る。
+  - 書き込む場所: `src/<slug>.tsx`, `server/api/<slug>/**`
+  - ページ: あり
+  - 作り方: `src/` にページ(`.tsx`)を置く。書く前に `agents/page.md`(API は `agents/api.md`)を読む。
+- **スライド** — 分析の示唆をまとめて誰かに伝えるとき(調査結果の報告、会議資料、施策の提案)。
+  結論 → 根拠 → 次の一手の順にまとめる。
+  - 書き込む場所: `src/<slug>.slide.tsx`, `vantage-slide/**`
+  - ページ: あり
+  - 作り方: `src/<slug>.slide.tsx` に `<SlideDeck>` を返すページを置く(`@squadbase/vantage/slide`)。
+    書く前に `agents/slide.md` を読み、`vantage-slide` Skill が未配置なら
+    `vantage add skill vantage-slide` で置いてから読む。
+- **ドキュメント** — 報告書・調査のまとめ・説明資料のように、文章と図表を上から読む形で残し
+  共有したいとき。
+  - 書き込む場所: `src/<slug>.doc.tsx`
+  - ページ: あり
+  - 作り方: `src/<slug>.doc.tsx` に `<Document>` を返すページを置く(`@squadbase/vantage/doc`。
+    ルートは `.doc` を除いた `/<slug>`)。数値はコードに直接書き、チャートは `@squadbase/vantage/components` のチャート部品を文中に置く。
+    書く前に `agents/doc.md` を読む。
+- **オートメーション** — 決まった時刻に集計・通知・定期レポートを回したいとき、しきい値で
+  アラートしたいとき。
+  - 書き込む場所: `automations/<slug>/**`, `pipelines/**`
+  - ページ: なし
+  - 作り方: `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 カードを
+`squadbase://page/<path>#<ref>`(スライド内なら `?p=<N>#<ref>`)のリンクで指し、その領域を開く。
+`<ref>` はページのソースに書かれた `data-sq-ref` の値で、過去の回答のリンクもこの値で今の画面を開く。
+
+```tsx
+<DashboardCardPreset data-sq-ref="revenue-trend" title="売上の推移">
+  <EChart option={trendOption(data)} height="320px" />
+</DashboardCardPreset>
+
+{kpis.map((kpi) => (
+  <DashboardCard key={kpi.id} data-sq-ref={kpi.id}>...</DashboardCard>
+))}
+```
+
+### 追加の不変条件
+
+- **意味のまとまった表示領域(グラフ・表・KPI カードなど)のルート要素に付ける。** 通常は
+  `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・連番から作らない。
+- **`.map` で描く領域は、データの安定したキー(`kpi.id` など)がこの形式を満たすときだけ `data-sq-ref={kpi.id}`
+  のように使う。** 日本語や空白を含むキーはそのまま使わず、変換もしない(変換規則が変わると値が変わる)。
+  その場合は静的な意味名を付けるか、付けない。
+- **ページ内で一意にする。**
+- **新しく作った・直した画面では付ける。更新では既存の値を変えない** — 領域の意味が変わったときだけ変える
+  (値を変えると、それを指していた過去のリンクが開けなくなる)。触っていない画面へ遡って付けることはしない。
+
+## ファイル内の書く順序(値 → 画面本体 → 子の部品)
+
+ページ・部品のファイルは、上から次の順に書く。
+
+1. `import`(と `definePage(...)`)
+2. **値** — データ・定数・列定義・小さな関数。短く
+3. **画面本体** — `export default` のコンポーネント
+4. **子の部品** — 大文字始まりの部品。`function` 宣言で書く
+
+理由: ファイルは上から順に書かれ、書きかけでもプレビューに反映される。**本体が書かれた時点で画面が出る。**
+値を本体より後ろに書くと、本体はまだ無い値を読むので、その値が書かれるまで画面が出ない。
+子の部品は後ろでよい — 未定義の部品はプレビューが仮の枠で埋める。
+
+```tsx
+import { definePage } from "@squadbase/vantage"
+
+export const page = definePage({ title: "売上" })
+
+const KPI_ITEMS: Kpi[] = [/* … */]           // 値は本体より上
+type Kpi = { label: string; value: number }
+
+export default function SalesPage() {         // 本体
+  return <KpiRow items={KPI_ITEMS} />
+}
+
+function KpiRow({ items }: { items: Kpi[] }) { /* … */ }  // 子の部品は下
+```
+
+### 追加の不変条件
+
+- **子の部品は `function` 宣言で書く。** 宣言は巻き上げられるので、本体より後ろでも安全。
+  `const Foo = () => …` のアロー関数は後ろに置くと、モジュール評価時に参照された瞬間に TDZ(初期化前参照)で落ちる。
+- **値(定数・データ・列定義・小さな関数)は本体より上。** 小文字の関数・hook も値として上に置く。
+- 型は消えるのでどこでもよい。値のそばに置く。
+- 順序だけのために、既に並んでいるファイルを書き換えない。
+
+## アプリの表示言語(`lang`)
+
+ルートの `src/_layout.tsx` の `export const lang = "en"` が `<html lang>` になる。**アプリの内容の言語に合わせて書き換える**
+(ユーザーが日本語で依頼している・画面の文言が日本語なら `"ja"`)。
+
+- `lang` は**リテラル文字列**(BCP 47。`"ja"` / `"en"` / `"ja-JP"`)。変数・テンプレート補間は読まれない。
+- 読まれるのは**ルートの `src/_layout.tsx` だけ**。入れ子の `_layout.tsx` やページには書かない。
+- 日本語アプリで `"en"` のままだと、スライドの文節改行(`word-break: auto-phrase`)が効かず、見出しが単語の途中で折れる。
+  スライドのツールバー文言も `lang` で切り替わる(`"ja"` なら日本語、`en*` なら英語)。
+- 値は消さない。指定が無いと `"en"` 扱いになる。