@squadbase/vantage-template 0.1.1-dev2.7fae7eb → 0.1.1-dev2.b6e5836

package/README.md

@@ -52,11 +52,21 @@ npx @squadbase/vantage-template add funnel --force      # Overwrite existing fil
 
 `add` replaces the entry page, so it warns before overwriting it, and it lists leftover files from a previously applied template (it never deletes them — you may have edited them). A project with pages on *both* sides — `src/` present but `index.tsx` / `_layout.tsx` / `styles.css` still at the root — is refused with the list of files to move into `src/` first: Vantage ignores the root ones, so `vantage check` already fails there with `SRC_DIR_SPLIT`.
 
+#### `theme <theme-id>`
+
+Apply a SquadKit theme (`neutral`, `ocean`, `forest`, `sunset`, `violet`, `rose`, `mono`; the old `default` / `calm` / `vivid` / `mono` are accepted too). Rewrites a marked range of the project's `styles.css` with the theme's colors, radius and font for both light and dark mode, leaving everything else intact. Re-running with the same theme changes nothing. Overrides you write *after* the range win over the theme.
+
+```bash
+npx @squadbase/vantage-template theme ocean
+npx @squadbase/vantage-template theme forest --dry-run
+npx @squadbase/vantage-template theme sunset --reset-chart   # drop a `chart` preset so the theme's chart colors apply
+```
+
 #### `chart <preset-name>`
 
 Switch the chart color preset. Rewrites a marked block of `--chart-1`–`--chart-5` inside the project's `styles.css` (under `src/` when that layout is in use), leaving any other overrides in that file intact. Re-running replaces the block rather than stacking.
 
-A new project starts on the `blue` preset — the base template ships that block already written, so `init` and the gallery previews show the same colors. This command swaps it for another preset.
+A new project starts on the `neutral` theme and has no chart range; this command (or `init --chart`) adds one, which takes precedence over the theme's chart colors. `theme <id> --reset-chart` removes it again.
 
 ```bash
 npx @squadbase/vantage-template chart ocean

package/base-template/.squadbase/skills/vantage-add-feature/SKILL.md

@@ -16,7 +16,7 @@ CLI は雛形を出すだけで、規約の遵守はこちらの責任。**追
 ```bash
 vantage add page  <name>    # ルートページ(.tsx)
 vantage add api   <name>    # server/api/**.ts の API モジュール
-vantage add ui    <name>    # registry から UI ソースを components/ui/ にコピー(src/ があればその中)
+vantage add ui    <name>    # /ui・/components の部品ソースを components/ui/ にコピー(src/ があればその中)
 vantage add block <name>    # registry からブロックを components/blocks/ にコピー(同上)
 ```
 
@@ -121,15 +121,17 @@ vantage add ui data-table       # → components/ui/data-table.tsx(編集可能
 vantage add block sales-overview # → components/blocks/sales-overview.tsx
 ```
 
-- **多くの UI コンポーネントは「import 専用」で、`add ui` でコピーできる名前は限られる。**
-  現在 registry からコピー可能なのは `data-table`(ui)と `sales-overview`(block)のみ。
-  未知の名前を渡すと利用可能な名前一覧を出して失敗する。
-- コピーが要らない大半のプリミティブは `@squadbase/vantage/ui` から、複合パーツは
-  `@squadbase/vantage/components` から**そのまま import**するのが基本(コピー不要)。
+- **基本はコピーせず import する。** プリミティブは `@squadbase/vantage/ui` から、複合パーツと
+  チャートは `@squadbase/vantage/components` から**そのまま import**する。
   ```tsx
   import { Button, Loading, ErrorState } from "@squadbase/vantage/ui"
-  import { DashboardCardPreset, DataTablePreset, EChart } from "@squadbase/vantage/components"
+  import { DashboardCardPreset, DataTablePreset, LineChart } from "@squadbase/vantage/components"
   ```
+- `add ui` は**改造したいときだけ**使う。`/ui` と `/components` の部品はすべて kebab-case 名で
+  コピーできる(`add ui bar-chart`・`add ui combobox`)。未知の名前を渡すと利用可能な名前一覧を
+  出して失敗する。
+- グラフは型付きチャート(`LineChart`・`BarChart` など)から選ぶ。選び方は `agents/page.md` の
+  「グラフはまず型付きチャートで描く」。
 - **props は `vantage docs <name>` で確認してから書く**(`vantage docs button`・
   `vantage docs parts/data-table`。名前が分からなければ `vantage search <やりたいこと>` で
   探してから `vantage docs` に渡す)。

package/base-template/.squadbase/skills/vantage-app/SKILL.md

@@ -14,7 +14,7 @@ description: Vantage(@squadbase/vantage)ダッシュボードアプリを一か
 
 ## 全体の流れ
 
-1. **骨組み** — `bun run dev` が上がるところまで
+1. **骨組み** — `pnpm dev` が上がるところまで
 2. **ルートを決める** — ページファイルを置き、`vantage routes` で URL を確認
 3. **データを繋ぐ** — 外部 API か、自前の `server/api` か
 4. **仕上げ** — `check` → `build` → `preview`
@@ -52,7 +52,7 @@ exit 1 になる。
 ```
 
 `index.tsx` はデフォルトエクスポートの React コンポーネント 1 つ(これが `/` になる)。あとは
-`bun install && bun run dev` で http://localhost:5173 が上がる(このプロジェクトの package manager は bun。`bun.lock` を持つ)。
+`pnpm install && pnpm dev` で http://localhost:5173 が上がる。
 
 **既存アプリに合流したときは、作る前に現状を読む:**
 
@@ -75,6 +75,10 @@ vantage add skill  # 配置済みの skill(このファイルの仲間)と、そ
 - 共通の枠(ヘッダ・サイドバー)は `_layout.tsx`、Not Found と例外は `_404.tsx` / `_error.tsx`。
 - 一覧 → 詳細を作るなら、**動的パラメータの「3 つの綴り」を先に決めてから**両方のファイルを
   書く。後から変えると静かにマッチしなくなる。
+- **ページになるのは tsx だけではない。** `.csv` / `.xlsx` を `src/` に置けば表として読めるページに
+  なり、`<name>.slide.tsx` はスライドデッキになる(どちらもナビに同格で並ぶ)。ダッシュボード・
+  スライド・データを 1 つのアプリに並べたいときは、まずこの 2 つで足りないか考える —— 表を出すために
+  ページを書く必要は無い。スライドの書き方は `vantage-slide` スキル。
 
 ## Step 3 — データを繋ぐ
 
@@ -105,10 +109,10 @@ vantage add skill  # 配置済みの skill(このファイルの仲間)と、そ
 ## Step 4 — 仕上げ
 
 ```bash
-bun run check     # エラーが残っていないか(exit 1 なら残っている)
-bun run routes    # 公開される URL の最終確認
-bun run build     # dist/ に client(+ server)+ vantage-manifest.json
-bun run preview   # 本番ビルドをローカルで動かす
+pnpm check     # エラーが残っていないか(exit 1 なら残っている)
+pnpm routes    # 公開される URL の最終確認
+pnpm build     # dist/ に client(+ server)+ vantage-manifest.json
+pnpm preview   # 本番ビルドをローカルで動かす
 ```
 
 `vantage-manifest.json` の `mode` は `server/` の有無から自動で決まる(手で書かない)。

package/base-template/.squadbase/skills/vantage-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vantage-design
-description: Vantage(@squadbase/vantage)アプリの見た目の意図 `DESIGN.md` と、実際の値を持つ `styles.css` をまとめて作る / 更新する手順。配色・ブランドカラー・テーマ・チャートの色・フォント・角丸・トーンを変えたいとき、既存サイトやロゴ・資料・外部の DESIGN.md に合わせたいとき、プロジェクト作成時の初期デザイン(プリセット default / calm / vivid / mono)を決めるときに使う。「色を変えて」「ブランドに合わせて」「このサイトに合わせて」「落ち着いた感じに」「フォントを変えて」「テーマを作って」「DESIGN.md を作って」、"change the colors", "match our brand", "match this website", "theme", "color palette", "font", "design system", "DESIGN.md" で起動。
+description: Vantage(@squadbase/vantage)アプリの見た目の意図 `DESIGN.md` と、実際の値を持つ `styles.css` をまとめて作る / 更新する手順。配色・ブランドカラー・テーマ・チャートの色・フォント・角丸・トーンを変えたいとき、既存サイトやロゴ・資料・外部の DESIGN.md に合わせたいとき、プロジェクト作成時の初期デザイン(テーマ neutral / ocean / forest / sunset / violet / rose / mono)を決めるときに使う。「色を変えて」「ブランドに合わせて」「このサイトに合わせて」「落ち着いた感じに」「フォントを変えて」「テーマを作って」「DESIGN.md を作って」、"change the colors", "match our brand", "match this website", "theme", "color palette", "font", "design system", "DESIGN.md" で起動。
 ---
 
 # DESIGN.md と styles.css をまとめて更新する
@@ -23,7 +23,7 @@ Vantage アプリの見た目は 2 つのファイルで決まる。
 | --- | --- |
 | `references/format.md` | `DESIGN.md` を書く / 直すとき(書式・節の順番・雛形) |
 | `references/extract.md` | URL・画像・pptx/pdf・言葉・外部 DESIGN.md から色と書体を取り出すとき |
-| `references/presets.md` | プロジェクト作成時の初期デザイン(`default` / `calm` / `vivid` / `mono`) |
+| `references/presets.md` | テーマ(`neutral` / `ocean` / `forest` / `sunset` / `violet` / `rose` / `mono`)の選び方と `theme` コマンド。旧プリセット id の読み替え |
 | `scripts/contrast.mjs` | 文字色と背景色のコントラスト比を確かめるとき |
 
 ## 手順
@@ -43,29 +43,32 @@ Vantage アプリの見た目は 2 つのファイルで決まる。
   各行に「何に合わせてその色にしたか」を 1 語添える。
 - **トーンの説明**(2〜3 行。`DESIGN.md` の「全体のトーン」にそのまま入る文)。
 
-プリセットで足りる場合はプリセット名(`references/presets.md`)で提案してよい。
+テーマで足りる場合はテーマ id(`references/presets.md`)で提案してよい。旧プリセット id(`default` / `calm` / `vivid` / `mono`)で頼まれたら新 id に読み替える。
 
 ### 3. styles.css と DESIGN.md を同じステップで書く
 
 `styles.css`:
 
-- **マーカーブロックの中は手で編集しない。**
-  ``/* vantage-template:chart-preset — regenerated by `chart`; edits here are lost */`` 〜
-  `/* vantage-template:chart-preset:end */` の間はコマンドが丸ごと書き換える生成物で、手で直した
-  値は次の適用で消える。
-- チャートの 5 色は必ずコマンドで選ぶ: `npx @squadbase/vantage-template chart <preset>`
-  (`blue` / `ocean` / `sunset` / `forest` / `berry` / `mono`。プロジェクトルートで実行。
-  `--dry-run` で書き込まずに結果を見られる)。マーカーの中だけが置き換わり、他の記述は残る。
-- プリセットに無いチャート色(ブランド色を `--chart-1` にしたいなど)は、マーカーブロックの**後ろ**に
+- **テーマ範囲・チャート範囲のマーカーの中は手で編集しない。** 色・角丸・書体の出発点は 7 テーマ
+  (`neutral` / `ocean` / `forest` / `sunset` / `violet` / `rose` / `mono`)から選び、コマンドで当てる:
+  `npx @squadbase/vantage-template theme <id>`(プロジェクトルートで実行。`--dry-run` で書き込まずに
+  結果を見られる)。``/* squadkit-theme — regenerated by `theme`; edits here are lost */`` 〜
+  `/* squadkit-theme:end */` の間はコマンドが丸ごと書き換える生成物で、手で直した値は次の適用で消える。
+  旧プリセット id(`default` → `neutral` / `calm` → `ocean` / `vivid` → `sunset` / `mono`)もコマンドが受ける。
+- チャートの 5 色はテーマが持つ。テーマと別の配色にしたいときだけ
+  `npx @squadbase/vantage-template chart <preset>`(`blue` / `ocean` / `sunset` / `forest` / `berry` / `mono`)を使う。
+  ``/* vantage-template:chart-preset … */`` 〜 `/* vantage-template:chart-preset:end */` の間が置き換わり、
+  テーマのチャート色より優先される。テーマに揃え直すには `theme <id> --reset-chart`。
+- プリセットに無いチャート色(ブランド色を `--chart-1` にしたいなど)は、**マーカーブロックの後ろ**に
   別の `:root { --chart-1: …; }` と `.dark, [data-theme="dark"] { --chart-1: …; }` を足して上書きする
-  (後に書いた方が勝つ)。上書きするのは変えたい番号だけにし、残りはプリセットに任せる。
-- `--primary` / `--primary-foreground` / `--radius` などチャート以外のトークンは、マーカーの**外**
-  (ファイル先頭の `:root` ブロック)に書く。色は `:root` と `.dark, [data-theme="dark"]` の
-  **両方**に書く。片方だけだとダークモードで既定に戻る。値は `oklch()` か Tailwind のパレット変数
-  (`var(--color-sky-600)`)で書く。
-- 書体は既定でシステムフォント。**ページの書体を決めるのは `body` セレクタの `font-family`**
-  (フレームワークの `theme.css` が `body` にシステムフォントを直接指定しているため、`:root` や
-  `html` に `font-family` を書いても本文には効かない)。スライドの書体は `:root` の
+  (後に書いた方が勝つ)。上書きするのは変えたい番号だけにし、残りはテーマに任せる。
+- `--primary` / `--primary-foreground` / `--radius` などテーマに無い値・ブランド色の上書きも、
+  **マーカーブロックの後ろ**(ファイル末尾)に書く。マーカーより前に書いた値はテーマに負ける。
+  色は `:root` と `.dark, [data-theme="dark"]` の**両方**に書く。片方だけだとダークモードでテーマの値に
+  戻る。値は `oklch()` か Tailwind のパレット変数(`var(--color-sky-600)`)で書く。
+- 書体は既定でシステムフォント。**ページの書体は `--font-sans`**(`styles.css` の `body` が
+  `font-family: var(--font-sans)` で参照する。テーマ範囲も `--font-sans` を持つので、書体を変えるには
+  マーカーブロックの後ろで `:root { --font-sans: …; }` を上書きする)。スライドの書体は `:root` の
   `--slide-font-display`(見出し)/ `--slide-font-body`(本文)で決まる。Web フォントを使うときの
   レシピ:
   1. Google Fonts の CSS
@@ -73,21 +76,30 @@ Vantage アプリの見た目は 2 つのファイルで決まる。
      から使う subset の `@font-face` ブロックだけを `styles.css` の先頭に貼る。
      **`@import url(...)` は使わない** ― `styles.css` はテーマの後ろに連結されるので
      「@import rules must precede all rules」の警告とともにビルドで捨てられる。
-  2. マーカーの外に次を書く(フォールバックは `theme.css` の既定と同じ並び):
+  2. マーカーブロックの後ろに次を書く(フォールバックは `theme.css` の既定と同じ並び):
 
      ```css
-     body {
-       font-family: "<Font>", ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
-     }
      :root {
-       --slide-font-display: "<Font>", system-ui, -apple-system, "Hiragino Kaku Gothic ProN", "Hiragino Sans", "Yu Gothic", Meiryo, sans-serif;
+       --font-sans: "<Font>", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Hiragino Sans", "Hiragino Kaku Gothic ProN", "Noto Sans JP", Meiryo, ui-sans-serif, system-ui, sans-serif;
+       --slide-font-display: "<Font>", -apple-system, BlinkMacSystemFont, "Segoe UI", "Hiragino Kaku Gothic ProN", "Hiragino Sans", "Yu Gothic", Meiryo, system-ui, sans-serif;
        --slide-font-body: var(--slide-font-display);
      }
      ```
 
+  欧文の Web フォントだけを先頭に足すときも、日本語の system face(`"Hiragino Sans"` 〜 `Meiryo`)は
+  必ず残す。消すとカナ・漢字がブラウザ任せのフォールバックになり、細く表示される。
+  `ui-sans-serif` / `system-ui` は日本語の face より**後ろ**に置く。日本語の Windows ではどちらも
+  Yu Gothic UI(UI のリサイズを避けるために字幅を詰めた書体)に解決され、カナがここで決まって
+  半角風に見える。macOS の Chrome は `-apple-system` を解釈しないので `BlinkMacSystemFont` も並べる。
+  既存アプリの `styles.css` の `body` に `font-family` が直書きされている(`var(--font-sans)` ではない)、
+  または `ui-sans-serif, system-ui, …` が先頭にある、`"Yu Gothic UI"` が残っているときは、
+  `body { font-family: var(--font-sans); }` に直し、書体は `--font-sans` に上の並びで書く。
   日本語の Web フォントは face が 100 を超えるので原則使わない(pptx 書き出しも壊れる。
   `vantage-slide` の `references/tokens.md` 参照)。
 
+長い表(ダッシュボード): カードに `max-h-*` + `overflow-y-auto` の縦スクロール領域を作らず、
+ページング付きの `DataTablePreset`(`enablePagination`)にする(ホイールや End キーがページに届かなくなるため)。
+
 `DESIGN.md`: `references/format.md` の書式で書く。**色コードを書かない**(トークン名だけ)。
 150 行を超えない(超えると `vantage check` が `DESIGN_MD_TOO_LONG` を出す)。ロゴなどの素材は
 `public/brand/logo.svg` のように `public/` 配下のパスで「ブランド素材」行に書く。

package/base-template/.squadbase/skills/vantage-design/references/extract.md

@@ -7,12 +7,13 @@
 3. **書体**(見出しと本文の `font-family`。システムフォントで足りるか)
 4. **トーン**(2〜3 語: 「落ち着いた」「明るい」「堅い」…)
 
-チャートの 5 色は、主色から直接作るより**主色に最も近いチャートプリセット**を選び、
-`npx @squadbase/vantage-template chart <preset>` で適用する方が安全(5 色の明度差・色覚多様性への
-配慮が済んでいる)。`styles.css` の `vantage-template:chart-preset` マーカーブロックの中は
+チャートの 5 色は、主色から直接作るより**主色に最も近いテーマ**を選び、
+`npx @squadbase/vantage-template theme <id>` で適用する方が安全(5 色の明度差・色覚多様性への
+配慮が済んでいる)。テーマと別のチャート配色が要るときは `chart <preset>`。`styles.css` の
+`squadkit-theme` / `vantage-template:chart-preset` のマーカーブロックの中は
 **手で編集しない**(次の適用で消える)。主色を `--chart-1` に入れたいときだけ、マーカーブロックの
 **後ろ**に `:root` と `.dark, [data-theme="dark"]` の `--chart-1` 上書きを足し、残り 4 色は
-プリセットに任せる。`--primary` や `--radius` もマーカーの外に書く。
+プリセットに任せる。`--primary` や `--radius` はマーカーブロックの後ろに書く。
 
 ## URL(既存サイトに合わせる)
 
@@ -36,7 +37,7 @@ grep -oE 'font-family:[^;]+' /tmp/site.css | sort | uniq -c | sort -rn | head
 3. **ボタン・リンクの色**: `a {` `.btn` `button` `[class*=primary]` のセレクタの `color` /
    `background-color`。出現回数の多い有彩色が主色。
 4. **背景**: `body` / `html` の `background`。暗ければ「暗い基調」。
-5. **書体**: `body` の `font-family`。Google Fonts の `<link>` があればその family 名。
+5. **書体**: `body` の `font-family`(書き込み先は `--font-sans`)。Google Fonts の `<link>` があればその family 名。
 
 注意:
 
@@ -66,18 +67,19 @@ grep -oE 'font-family:[^;]+' /tmp/site.css | sort | uniq -c | sort -rn | head
 
 ## 言葉だけ(「落ち着いた感じに」)
 
-形容詞を `presets.md` の 4 つに寄せ、そのうえで主色だけを調整する。
+形容詞を `presets.md` の 7 テーマに寄せ、そのうえで主色だけを調整する。
 
 | 言われたこと | 出発点 |
 | --- | --- |
-| 落ち着いた・信頼感・堅い・経営向け・青系 | `calm` |
-| 明るい・元気・勢い・暖かい・営業向け | `vivid` |
+| 落ち着いた・信頼感・堅い・経営向け・青系 | `ocean` |
+| 明るい・元気・勢い・暖かい・営業向け | `sunset` |
 | シンプル・モノクロ・印刷する・資料に貼る | `mono` |
-| 特に無し・標準・おまかせ | `default` |
-| 自然・環境・緑 | `default` の構成でチャートを `forest` に |
-| 華やか・ポップ・紫やピンク | `default` の構成でチャートを `berry` に |
+| 特に無し・標準・おまかせ | `neutral` |
+| 自然・環境・緑 | `forest` |
+| 華やか・ポップ・紫 | `violet` |
+| 華やか・ポップ・ピンク | `rose` |
 
-当てはまらない言葉は、2 案(例: `calm` と `default`)を並べて選んでもらう。
+当てはまらない言葉は、2 案(例: `ocean` と `neutral`)を並べて選んでもらう。
 
 ## 外部の DESIGN.md(Stitch などが書いたもの)
 
@@ -99,8 +101,8 @@ Vantage の `DESIGN.md` は値を持たないので、**値を `styles.css` へ
    | error | `--destructive` |
    | success / warning | 専用トークンなし → `--chart-*` のどれかに割り当てて `DESIGN.md` に書く |
    | radius / corner | `--radius` |
-   | display / headline font | `--slide-font-display`(+ ページの見出しなら `body` の font-family) |
-   | body font | `body` セレクタの font-family と `--slide-font-body`(`:root` の font-family は効かない) |
+   | display / headline font | `--slide-font-display`(+ ページの見出しなら `--font-sans`) |
+   | body font | `--font-sans`(ページ本文)と `--slide-font-body` |
 
 3. `styles.css` のマーカーブロックの外に、`:root` と `.dark, [data-theme="dark"]` の両方で書く
    (チャート色・書体の書き方は SKILL.md の手順 3)。外部の DESIGN.md に

package/base-template/.squadbase/skills/vantage-design/references/format.md

@@ -50,8 +50,8 @@ Components → 「成果物の種類ごとの規則」/ Do's and Don'ts。値は
 
 - `--muted` `--accent` `--secondary` `--border` は背景・境界用。文字色の役割に割り当てない。
 - 良い / 注意の専用トークンは無い。`--chart-*` の中から割り当てるか、「専用トークンなし」と書く。
-- ページ本文の書体はトークンではなく `body` の `font-family`(`styles.css` の `body` セレクタで上書きする。
-  `:root` / `html` に書いても `theme.css` の `body` 指定に負けて効かない)。
+- ページ本文の書体は `--font-sans`(`styles.css` の `body` が `font-family: var(--font-sans)` で参照する。
+  テーマを当てると `--font-sans` もテーマの値になる。変えるときはテーマ範囲のマーカーの後ろで上書きする)。
 - `--slide-bg` などは既定で `--background` などの別名。`.dark` に書き直す必要は無い。
 
 ## 雛形(中立の既定テーマ)
@@ -112,14 +112,15 @@ DESIGN.md — このアプリの「見た目の意図」を書くファイルで
 - 系列は 5 つまで。それ以上はグループ化するか「その他」にまとめる。
 - 禁止: 同じチャートで `--destructive` を普通の系列色として使う(悪い値に見える)。
 - 禁止: 隣り合う系列に `--chart-3` と `--chart-4` を並べて細い線で描く(見分けにくい)。
-- 配色を丸ごと変えるときは `npx @squadbase/vantage-template chart <preset>` を使う
-  (`blue` / `ocean` / `sunset` / `forest` / `berry` / `mono`)。
+- 配色を丸ごと変えるときは `npx @squadbase/vantage-template theme <id>` を使う
+  (`neutral` / `ocean` / `forest` / `sunset` / `violet` / `rose` / `mono`)。チャートだけ別の配色にするときは
+  `chart <preset>`(`blue` / `ocean` / `sunset` / `forest` / `berry` / `mono`)。
 
 ## 書体 (Typography)
 
 | 用途 | 指定 | 備考 |
 | --- | --- | --- |
-| 見出し・本文 | システムフォント(`body` の `font-family`) | Web フォントは使わない |
+| 見出し・本文 | 日本語を含むシステムフォント(`--font-sans`) | Web フォントは使わない |
 | 数字 | 同上 + `tabular-nums` | 桁がそろうように必ず付ける |
 | スライドの見出し | `--slide-font-display` | 既定は日本語を含むシステムフォント |
 | スライドの本文 | `--slide-font-body` | 既定は見出しと同じ |

package/base-template/.squadbase/skills/vantage-design/references/presets.md

@@ -1,110 +1,60 @@
-# 初期デザインのプリセット
-
-プロジェクト作成時に選ぶ 4 つの出発点。**id(`default` / `calm` / `vivid` / `mono`)はプロジェクト
-作成のワークフローが参照するので変えないこと。** どれも「チャートのプリセット 1 つ + `--primary` +
-`DESIGN.md` の差分」でできている。**`--primary` はどのプリセットでも必ず書く**(無彩色のプリセットも
-値を明示する)。チャートだけ変えるとホームのような色の少ない画面では見た目が変わらず、別のプリセットから
-切り替えたときに前の `--primary` が残るため。
-
-適用の手順は共通:
-
-1. `npx @squadbase/vantage-template chart <チャートのプリセット>` で `styles.css` のマーカーブロックを
-   差し替える。**マーカーブロックの中(`--chart-1..5`)は手で編集しない** ― コマンドの生成物で、
-   次の適用で消える。
-2. 各プリセットの `--primary` / `--primary-foreground` を、`styles.css` のマーカーの**外**(先頭の
-   `:root` ブロック)に `:root` と `.dark, [data-theme="dark"]` の両方で書く。既にある `--primary` は置き換える。
-3. `DESIGN.md` を `format.md` の雛形から作り、下の「DESIGN.md の差分」の行だけを書き換える。
-4. `scripts/contrast.mjs` で `--primary-foreground` / `--primary` をライトとダークで確かめる。
-
-| id | トーン | チャートのプリセット | `--primary` |
-| --- | --- | --- | --- |
-| `default` | 無彩色のベース。色を持つのはデータ(`blue` チャート)だけ | `blue` | 無彩色(`theme.css` の既定値を明示) |
-| `calm` | 落ち着いた寒色。報告書・経営向け | `ocean` | 深い青(スカイ 700 / 300) |
-| `vivid` | 明るい暖色。営業・マーケティング向け | `sunset` | 濃いオレンジ(オレンジ 700 / 400) |
-| `mono` | モノクロ。印刷・資料への貼り付け向け | `mono` | ジンク 900 / 200 |
-
-## `default`
-
-- トーン: 落ち着いた無彩色のベースに、データだけが色を持つ業務ダッシュボード。装飾より読みやすさ。
-- チャート: `blue`(青 → ティール → フクシア → バイオレット → グレー)。
-- `--primary`(フレームワークの既定と同じ無彩色。他のプリセットから戻すときのために明示する):
-
-  ```css
-  :root {
-    --primary: oklch(0.205 0 0);
-    --primary-foreground: oklch(0.985 0 0);
-  }
-  .dark,
-  [data-theme="dark"] {
-    --primary: oklch(0.922 0 0);
-    --primary-foreground: oklch(0.205 0 0);
-  }
-  ```
-
-- `DESIGN.md`: 雛形そのまま(`format.md` の雛形は `default` を説明している)。
-
-## `calm`
-
-- トーン: 寒色でまとめた静かな画面。強調は控えめにし、数字と罫線で読ませる。
-- チャート: `ocean`(スカイ → シアン → インディゴ → ティール → スレート)。
-- `--primary`(チャートのスカイに揃えた深い青):
-
-  ```css
-  :root {
-    --primary: var(--color-sky-700);
-    --primary-foreground: oklch(0.985 0 0);
-  }
-  .dark,
-  [data-theme="dark"] {
-    --primary: var(--color-sky-300);
-    --primary-foreground: oklch(0.205 0 0);
-  }
-  ```
-
-- `DESIGN.md` の差分: 「全体のトーン」を上の文に。チャートの色味を「スカイ → シアン → インディゴ →
-  ティール → スレート」に。良い = `--chart-4`(ティール)。1 系列の強調は `--chart-1` + 残り `--chart-5`。
-  禁止: `--chart-1` と `--chart-2` を隣り合う細い線で並べる(どちらも明るい青系)。
-
-## `vivid`
-
-- トーン: 明るく勢いのある暖色。KPI とトレンドを大きく見せ、強調色をはっきり使う。
-- チャート: `sunset`(オレンジ → アンバー → ローズ → イエロー → ストーン)。
-- `--primary`(オレンジ 600 は白文字で 4.5:1 に届かないので 700 を使う):
-
-  ```css
-  :root {
-    --primary: var(--color-orange-700);
-    --primary-foreground: oklch(0.985 0 0);
-  }
-  .dark,
-  [data-theme="dark"] {
-    --primary: var(--color-orange-400);
-    --primary-foreground: oklch(0.205 0 0);
-  }
-  ```
-
-- `DESIGN.md` の差分: トーンを上の文に。主色の行を「濃いオレンジ」に。良い = 専用色なし(▲ と
-  `--foreground`)、悪い = `--destructive`。禁止: `--chart-3`(ローズ)と `--destructive` を同じ
-  チャートに置く(悪い値と区別できない)。1 系列の強調は `--chart-1` + 残り `--chart-5`。
-
-## `mono`
-
-- トーン: 白黒と灰色だけ。色で意味を運ばず、太さ・順番・ラベルで読ませる。
-- チャート: `mono`(ジンク 900 → 200。ダークでは反転)。
-- `--primary`(チャートの両端と同じジンク):
-
-  ```css
-  :root {
-    --primary: var(--color-zinc-900);
-    --primary-foreground: oklch(0.985 0 0);
-  }
-  .dark,
-  [data-theme="dark"] {
-    --primary: var(--color-zinc-200);
-    --primary-foreground: oklch(0.205 0 0);
-  }
-  ```
-
-- `DESIGN.md` の差分: トーンを上の文に。強調 = `--chart-1`(最も濃い灰)。良い = 専用色なし(▲ と
-  符号)、悪い = `--destructive`(**画面で唯一の有彩色**として使う)。チャートは系列を 3 つまでにし、
-  それ以上は直接ラベルを付ける。禁止: 隣り合う `--chart-4` と `--chart-5`(明度差が小さい)。
+# 初期デザイン(テーマ)
+
+プロジェクトの見た目の出発点は、SquadKit の 7 テーマから選ぶ。**テーマ id はプロジェクト作成の
+ワークフローが参照するので変えないこと。** テーマは主色・背景・文字・境界・チャート 5 色・角丸・書体を
+まとめて持つ(ライトとダークの両方)。
+
+| id | トーン | 向く場面 |
+| --- | --- | --- |
+| `neutral` | 既定。Vantage の素の見た目(青の主色と無彩色の面) | 迷ったとき・おまかせ |
+| `ocean` | 青を基調にした落ち着いた信頼感。角丸はやや小さめ | 報告書・経営向け |
+| `forest` | 緑を基調にした自然な印象。丸ゴシック系の書体、角丸はやや小さめ | 環境・ヘルスケア・自然 |
+| `sunset` | 橙を基調にした温かみ。角丸はやや大きめ | 営業・マーケティング |
+| `violet` | 紫を基調にしたやわらかい印象。角丸は大きめ | 華やかさ・ポップ |
+| `rose` | 赤紫からピンクの落ち着いた色。角丸は大きめ(`--destructive` の赤とは別の色) | 華やかさ・ポップ |
+| `mono` | 無彩色寄り。チャートも彩度を抑え、角丸は最小。等幅フォント | 印刷・資料への貼り付け |
+
+## 当てる
+
+プロジェクトルートで次を実行する。`--dry-run` で書き込まずに結果を見られる。
+
+```bash
+npx @squadbase/vantage-template theme <id>
+npx @squadbase/vantage-template theme ocean --reset-chart   # chart コマンドで選んだ配色を捨て、テーマのチャート色に揃える
+```
+
+- `styles.css` の ``/* squadkit-theme — regenerated by `theme`; edits here are lost */`` 〜
+  `/* squadkit-theme:end */` の範囲(テーマ範囲)だけを差し替える。**範囲の中は手で編集しない**。
+  マーカーが無いファイルには自動で足される。同じ id を再実行しても変わらない。
+- テーマ範囲はファイル先頭の `:root` より後ろに置かれ、同じ詳細度なら後ろが勝つ。
+  先頭の `:root` に手書きした `--primary` などはテーマに負ける。
+- `chart <preset>` の範囲(`--chart-*` だけ)はテーマ範囲の**後ろ**に置かれ、テーマのチャート色に勝つ。
+  チャートの配色もテーマに任せるなら `--reset-chart` で外す。
+
+## 旧プリセット id の読み替え
+
+古い呼び出しの `default` / `calm` / `vivid` / `mono` は、`theme` コマンドがそのまま受けて次の id として扱う。
+
+| 旧 | 新 |
+| --- | --- |
+| `default` | `neutral` |
+| `calm` | `ocean` |
+| `vivid` | `sunset` |
+| `mono` | `mono` |
+
+## テーマに無い値(ブランド色など)
+
+テーマの `--primary` を変えたい、特定の色だけブランドに合わせたい、というときは、テーマを当てたうえで
+**`/* squadkit-theme:end */`(チャート範囲があればその終端)より後ろ**に、変えたいトークンだけ
+`:root` と `.dark, [data-theme="dark"]` の**両方**に書く。前に書くとテーマに負ける。
+`scripts/contrast.mjs` で `--primary-foreground` / `--primary` をライトとダークで確かめる。
+
+## DESIGN.md
+
+`format.md` の雛形から作り、選んだテーマに合わせて次の行だけ書き換える。
+
+- 「全体のトーン」: 上の表のトーンを 2〜3 行に。
+- 主色の行: テーマの主色の色味(「青」「橙」など。**色コードは書かない**)。
+- チャートの色味: テーマの `--chart-1..5` の並び(適用後の `styles.css` を見る)。
+- 良い / 悪い / 注意: 専用トークンは無い。`--chart-*` から割り当てるか「専用トークンなし」と書く。
+  `--destructive` を普通の系列色に使わない。

package/base-template/.squadbase/skills/vantage-pitfalls/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vantage-pitfalls
-description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、Select の value/label、クライアントから server/ を import しない、EChart の配色と高さ、動的パラメータの3綴り同期、PUBLIC_ env、HttpError など。Vantage の UI コンポーネントやルーティングが思った通りに動かないとき、ビルドやスタイルが静かに欠落するときに参照する。
+description: Vantage(@squadbase/vantage)アプリを書くときに静かに壊れる落とし穴のリファレンス。Base UI は Radix ではない(asChild 無し・render プロップ)、Select の value/label、クライアントから server/ を import しない、チャートの色指定と EChart の配色・高さ、動的パラメータの3綴り同期、PUBLIC_ env、HttpError、csv/xlsx ページの URL 衝突とサイズ上限、スライドの data-waitfor など。Vantage の UI コンポーネントやルーティングが思った通りに動かないとき、ビルドやスタイルが静かに欠落するときに参照する。
 ---
 
 # Vantage アプリの落とし穴リファレンス
@@ -59,6 +59,10 @@ Base UI の `SelectValue` は選択中の **value をそのまま描き**、`Sel
 
 ## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
 
+ふつうの推移・比較・構成比は型付きチャート(`LineChart`・`BarChart` など。→ `agents/page.md`)で
+描く。その `colors` に渡すのはトークン名 `"chart-1"`〜`"chart-5"` か CSS 色で、Tailwind クラス
+(`"bg-blue-500"` など)は効かない。以下は `EChart` を直接使うときの話。
+
 系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれる
 (init 時にトークンの実値を解決している)。ライト / ダークの切り替えにも、`styles.css` の
 書き換えやテーマプリセットの適用にも追従する。
@@ -90,6 +94,11 @@ Base UI の `SelectValue` は選択中の **value をそのまま描き**、`Sel
 - 表示ルート `/sales/:customerId`
 - リンク `to="/sales/$customerId"` + `params={{ customerId }}` / 取り出し `useParams().customerId`
 
+## 日本語アプリは `lang` を指定する
+
+ルート `src/_layout.tsx` に `export const lang = "ja"`(リテラル)が無いと `<html lang="en">` のままで、
+スライドの見出しが文節の途中で折れる。内容が日本語なら必ず指定する。
+
 ## ページ:`definePage` の値はリテラルで書く
 
 title/description/navLabel は**ビルド時に静的抽出**される。変数・関数呼び出し・テンプレート補間を
@@ -153,6 +162,46 @@ import { type ColumnDef } from "@squadbase/vantage/components"
 const columns: ColumnDef<Row>[] = [ … ]   // 注釈しないと accessorKey が string に広がり弾かれる
 ```
 
+## データファイルページ:同名の tsx と衝突する / ブラウザでパースされる
+
+`src/` に置いた `.csv` / `.xlsx` はページになる。ここで静かに壊れるのは 3 つ。
+
+- **`sales.csv` と `sales.tsx` はどちらも `/sales`** に解決するので `ROUTE_CONFLICT` エラー。
+  `.slide.tsx` も同じ(`june.slide.tsx` と `june.tsx`)。
+- **パースはブラウザで走る。** 25MB を超えるファイルはそのページがエラー表示になる
+  (`vantage check` が `FILE_PAGE_TOO_LARGE` で先に警告する)。大きいデータは `server/api/` から
+  配って `DataTable` で描く。
+- **ビューアの無い拡張子(`.xls`・`.ods`・`.tsv` など)はルートにならない。** 404 ですらなく、
+  ナビにも `vantage routes` にも出ない。`vantage check` の `UNSUPPORTED_PAGE_FILE` 警告が
+  唯一の告知点なので、「置いたのに出てこない」ときはまず `check` を見る。
+
+ビューアは**表計算ソフトの見た目の読み取り専用グリッド**(列は A / B / C、左に行番号、1 行目は
+固定、シートのタブは下端)。**ソート・フィルタ・ページネーションは持たない** —— 並べ替えや
+絞り込みが要るなら `server/api/` から配って `DataTable` で描く。数式・グラフ・セル書式は
+再現されない(値として読めれば十分、という設計)。
+
+## スライド:`data-waitfor` を忘れるとチャートが白紙で書き出される
+
+`.slide.tsx` の pptx 書き出しはスライドを画像として焼く。**canvas に描くもの(`EChart`)は
+描き終わりを待たせないと、描画前に撮られてそのスライドだけ白紙になる**:
+
+```tsx
+<div data-waitfor="canvas">
+  <EChart option={option} style={{ width: 1400, height: 600 }} />
+</div>
+```
+
+ほかに 2 つ。
+
+- **`@squadbase/vantage/ui` のプリミティブをスライドに置かない。** UI キットは rem と Tailwind で
+  組まれているので、1920×1080 を縮小投影すると `text-sm` のボタンが実効 8px 程度になって読めない。
+  スライドは絶対 px のインラインスタイルで書く。
+- **dev サーバーを起動したあとに最初の `.slide.tsx` を新規作成した場合、初回の pptx 書き出しで
+  1 回だけリロードが入る。** 書き出し用の依存はプロジェクトがデッキを持つときだけ宣言される仕組みで、
+  その判定は dev の起動時に 1 度しか走らないため。`vantage dev` を再起動すれば解消する。
+
+書き方の作法(キャンバスの縦方向の予算、段階表示、トランジション、モーフ)は `vantage-slide` スキル。
+
 ## 生成物:`.vantage/` と `dist/` は触らない
 
 どちらも gitignore 済みの生成物。編集しても次のコマンドで上書きされる。`.vantage/` は任意の CLI