@squadbase/vantage 0.6.2-dev1.42c4e48 → 0.6.2-dev1.81c1bbe

package/templates/agents/doc.md

@@ -15,6 +15,13 @@ import { definePage } from "@squadbase/vantage"
 import { BarChart } from "@squadbase/vantage/components"
 import { Document } from "@squadbase/vantage/doc"
 
+const weekly = [
+  { week: "第1週", 売上: 1180 },
+  { week: "第2週", 売上: 1240 },
+  { week: "第3週", 売上: 1210 },
+  { week: "第4週", 売上: 1620 },
+]
+
 export const page = definePage({ title: "6月度サマリー", navLabel: "6月度サマリー" })
 export default function JuneSummary() {
   return (
@@ -50,6 +57,27 @@ export default function JuneSummary() {
 - **ページ全体を包むのは `<Document>` だけ。** `PageShell` などのダッシュボード用の枠で包まない
   (本文の幅と余白は `<Document>` が決めます)。
 
+## まず block を探す
+
+1 節分の中身は、手で組む前に `@squadbase/vantage/doc` の block から探します(`<Document>` の直下に
+並べる。多くは 1 block = 1 節。`DocCallout`・`DocFigure`・`DocDataTable` は節ではなく、節の中(本文の間)に置く部品)。props は `vantage docs <name>`(例: `vantage docs doc-kpi-scorecard`)で引く。
+
+| block | 用途 |
+| --- | --- |
+| `DocReportHeader` | レポートの冒頭(タイトル・サブタイトル・対象期間・データ時点・作成者・出典) |
+| `DocExecutiveSummary` | 結論を先に述べる要約の節 |
+| `DocKpiScorecard` | 主要指標をまとめたスコアカード |
+| `DocFigure` | 図表 1 つとキャプション(チャートは children で渡す) |
+| `DocDataTable` | 素の `table` による表 |
+| `DocCallout` | 補足・示唆・注意・決定の囲み(`kind`: `note` / `insight` / `warning` / `decision`) |
+| `DocKeyFindings` | 主要な発見の箇条 |
+| `DocActionItems` | 次のアクション(担当・期限つき) |
+
+**props の渡し方は block 間で共通。** 数値は `value: number | null` と `format`(整形は block がする。表示を上書きするときだけ `display`。`null` は「—」)。前期比などは `delta: { value, format? }` と `comparisonLabel`(例 `"前年同期比"`)、良し悪しは指標ごとの `betterWhen`(`"up"` が既定、コストなど下がるほど良いものは `"down"`。向きは block が符号から出す)。目標は `target: number`。出典は `source`、時点は `asOf` に**日付だけ**(例 `"2026-09-30"`。「データ時点」は block が付けるので「時点」を書かない)。時系列は、単一系列なら `{ x, y }[]`(`trend`)。
+
+block が合わない**1 節だけ**を素の HTML 要素で手で書く。import 元は `@squadbase/vantage/doc` のままで、
+block のための新しい import 元はありません。本文は文字列か ReactNode で渡し、Markdown 文字列は渡さない。
+
 ## 見た目を変える
 
 配色・書体・本文の幅は `--doc-*` の CSS 変数です。既定値はアプリのトークンへの別名なので、
@@ -74,3 +102,20 @@ export default function JuneSummary() {
 `.doc` を付けられるのはルートになるページモジュールだけで、`_layout.doc.tsx` などは
 `INVALID_PAGE_VARIANT` エラーになります。`june.doc.tsx` と `june.tsx` は同じ URL に解決するので
 `ROUTE_CONFLICT` です。
+
+## ファイル形式の規約
+
+置き場所・URL・default export・`definePage` の書き方は全ページ共通(`agents/page.md` の
+「ページファイルの規約」)。ここではドキュメント固有のものだけを挙げます。
+
+**MUST**
+
+- ファイル名は `<name>.doc.tsx`(`.jsx` も可)。サフィックスは小文字で 1 つだけ。`.doc.mdx` は
+  `INVALID_PAGE_VARIANT`、`.DOC.tsx`・二重サフィックスは黙って通常ページになる
+- default export は `<Document>` をルートに返す。フレームワークは包まない
+- ドキュメントの部品は `@squadbase/vantage/doc` から import する
+
+**SHOULD**
+
+- `PageShell` で包まない・PDF の保存ボタンを自作しない(上の「書き方」)
+- 数値はコードに直接書き、いつ時点の値かを本文に書く

package/templates/agents/page.md

@@ -71,6 +71,7 @@ URL になる。各ページは**デフォルトエクスポートの React コ
 | `_404.tsx` | Not Found ページ |
 | `_error.tsx` | ルートが throw したときのエラーページ |
 | `monthly-report.slide.tsx` | `/monthly-report`(スライドデッキ。詳しくは `agents/slide.md`) |
+| `june-summary.doc.tsx` | `/june-summary`(ドキュメント。詳しくは `agents/doc.md`) |
 | `sales-export.csv` | `/sales-export`(詳しくは `agents/csv.md`) |
 | `data/june.xlsx` | `/data/june`(詳しくは `agents/xlsx.md`) |
 
@@ -89,6 +90,26 @@ export default function MonthlyAnalysis() {
 }
 ```
 
+### ページファイルの規約(`.tsx` / `.slide.tsx` / `.doc.tsx` 共通)
+
+**MUST**
+
+- ページルートの配下に置く。`components/` などの走査対象外のディレクトリに置いたファイルはページに
+  ならず、エラーも出ない。`_` 始まりの名前は予約名(`_layout` / `_404` / `_error`)にだけ使う
+  (それ以外の `_` 始まりはページにならない。予約名にサフィックスを付けると `INVALID_PAGE_VARIANT`)
+- URL はサフィックスと拡張子を除いたパスで決まる。同じ URL になる別ファイル(`june.tsx` /
+  `june.slide.tsx` / `june.doc.tsx` / `june.csv`)を並べない(`ROUTE_CONFLICT`)。テンプレートの
+  未編集の `index.tsx` だけは例外で、`index.slide.tsx` / `index.doc.tsx` が `/` を取れる
+- default export は React の関数コンポーネント(無いと `MISSING_DEFAULT_EXPORT`。関数かどうかは
+  検査されない)
+- `definePage({ ... })` にはオブジェクトリテラルを直接渡し、`title` / `description` / `navLabel` は
+  文字列リテラルで書く。ビルド時に静的抽出されるので、変数・関数呼び出し・spread・shorthand・
+  `${}` を含むテンプレート文字列は**エラーにならず黙ってメタなし**になる
+
+**SHOULD**
+
+- `definePage` に `title` と `navLabel` を書く(ナビの表示名とブラウザのタブ名になる)
+
 ### ナビはルート一覧から組む
 
 `useRoutes()` がページルート一覧(スキャン順)を返すので、リンク配列を手で持たない。
@@ -109,7 +130,7 @@ routes.map((r) => (
 ```
 
 `RouteInfo`: `path`(`/sales/:id`)・`to`(`/sales/$id`)・`params`・`dynamic`・`index`・`label`・
-`title`・`description`・`navLabel`・`kind`(`"module"` | `"file"`)・`variant`(`"slide"`)。
+`title`・`description`・`navLabel`・`kind`(`"module"` | `"file"`)・`variant`(`"slide"` | `"doc"`)。
 後ろの 2 つで、ナビをダッシュボード / スライド / データに分けたりアイコンを変えたりできます。
 
 ### フィルタ状態は URL に置く
@@ -177,6 +198,16 @@ refetchOnWindowFocus false・networkMode "always")。挙動を変えたいとき
   `/components` の複合パーツも全部取り出せる(名前は kebab-case: `add ui bar-chart`。
   ブロックは `add block sales-overview`。未知名で実行すると候補が一覧表示される)。
 
+### 長い表はページングする(縦スクロール箱を作らない)
+
+- 行が多い表は `DataTablePreset`(または `DataTable`)に `enablePagination` を付けて**ページング**する
+  (既定は 10 行 / ページ。ページングは既定で無効なので、付け忘れると全行が並ぶ)。素の `<table>` を
+  手書きして全行を流し込まない。
+- カードの中に `max-h-*` + `overflow-y-auto` の**縦スクロール領域を作らない**。ホイールやキー
+  (End / Space)がその箱に吸われ、ページ全体がスクロールしなくなる。高さは内容に任せる。
+- 横に広い表の `overflow-x-auto` は構わない。`SheetGrid`(`.csv` / `.xlsx` のビューア)は
+  グリッドとして意図した入れ子スクロールなので対象外。
+
 ### グラフはまず型付きチャートで描く
 
 - 推移は `LineChart` / `AreaChart`、比較は `BarChart`、構成比は `DonutChart`。`data`(行の配列)・

package/templates/agents/slide.md

@@ -19,6 +19,7 @@
 - 新規プロジェクトでまだ `/` が空いている場合のみ、`index.slide.tsx` を使ってよい。
 
 ```tsx
+import { definePage } from "@squadbase/vantage"
 import { Slide, SlideDeck } from "@squadbase/vantage/slide"
 
 export const page = definePage({ title: "6月度レビュー", navLabel: "6月度" })
@@ -34,8 +35,10 @@ export default function Deck() {
 
 **`<Slide>` は `<SlideDeck>` の直接の子に書く。** `SlideDeck` は直下の `<Slide>` 要素だけを数えるので、
 `<Slide>` を自作コンポーネント(`<Slide1 />` など)や Fragment で包むと 1 枚も数えられず「1 / 0」に
-なります(`{items.map((x) => <Slide key={x.id}>…</Slide>)}` のような配列は可)。共通の部品は
-`<Slide>` の**中**に置くコンポーネントとして切り出します(`<Slide><CoverPage /></Slide>`)。
+なります(`{items.map((x) => <Slide key={x.id}>…</Slide>)}` のような配列はファイル形式としては可。
+1 枚の中で視覚要素を `map` で量産しない方針は `vantage-slide` skill の「繰り返す要素は `map` ではなく
+コンポーネント」)。共通の部品は `<Slide>` の**中**に置くコンポーネントとして切り出します
+(`<Slide><CoverPage /></Slide>`)。
 
 1920×1080 の固定キャンバスに絶対 px で書き、画面サイズに合わせて縮小されます。キー / クリックで
 送れ、左のスライド一覧(サムネイル列)は `L` で開閉、`F` で全画面、ツールバーから pptx を
@@ -51,3 +54,53 @@ pptx が壊れる条件、説明と図表のデータ時点の揃え方)。
 `.slide` を付けられるのはルートになるページモジュールだけで、`_layout.slide.tsx` などは
 `INVALID_PAGE_VARIANT` エラーになります。`june.slide.tsx` と `june.tsx` は同じ URL に解決するので
 `ROUTE_CONFLICT` です。
+
+## まず block を探す
+
+1 枚分の中身は、手で組む前に `@squadbase/vantage/slide` の block から探します(`<Slide>` の**中**に
+置く。ルートは 100% で、`<Slide>` 自体は持たない)。props は `vantage docs <name>`(例:
+`vantage docs slide-kpi-hero`)で引く。
+
+| block | 用途 |
+| --- | --- |
+| `SlideCover` | 表紙(タイトル・サブタイトル・期間) |
+| `SlideExecSummary` | 結論を先に述べるエグゼクティブサマリー |
+| `SlideKpiHero` | 主要な KPI 1 つを大きく見せる |
+| `SlideKpiGrid` | 複数の KPI を並べる |
+| `SlideChartInsight` | チャート 1 つと、そこから読み取れること |
+| `SlideScorecardTable` | 指標と目標・達成度を表にしたスコアカード |
+| `SlideNextActions` | 次のアクション(担当・期限つき) |
+
+```tsx
+import { Slide, SlideDeck, SlideCover, SlideExecSummary } from "@squadbase/vantage/slide"
+// <SlideDeck><Slide><SlideCover … /></Slide><Slide><SlideExecSummary … /></Slide></SlideDeck>
+```
+
+**props の渡し方は block 間で共通。** 数値は `value: number | null` と `format`(整形は block がする。表示を上書きするときだけ `display`。`null` は「—」)。前期比などは `delta: { value, format? }` と `comparisonLabel`(例 `"前年同期比"`)、良し悪しは指標ごとの `betterWhen`(`"up"` が既定、コストなど下がるほど良いものは `"down"`。向きは block が符号から出す)。目標は `target: number`。出典は `source`(文字列)、時点は `asOf` に**日付だけ**(例 `"2026-09-30"`。「時点」は block が付けるので書かない)。時系列は、単一系列なら `{ x, y }[]`(kpi-hero・scorecard の `trend`)、複数系列なら `{ categories, series }`(chart-insight の `chart`)。
+
+block が合わない**1 枚だけ**を手で書く(デッキ全体を手書きに切り替えない)。import 元は
+`@squadbase/vantage/slide` のままで、block のための新しい import 元はありません。
+
+## ファイル形式の規約
+
+置き場所・URL・default export・`definePage` の書き方は全ページ共通(`agents/page.md` の
+「ページファイルの規約」)。ここではスライド固有のものだけを挙げます。**中身の値(キャンバス・
+セーフエリア・グリッド・文字サイズ・余白)は `vantage-slide` skill を参照。**
+
+**MUST**(破ると黙って壊れるものが多い。`vantage check` が拾うのは名前の誤りだけ)
+
+- ファイル名は `<name>.slide.tsx`(`.jsx` も可)。サフィックスは小文字で 1 つだけ。`.slide.ts` は
+  `INVALID_PAGE_VARIANT`、`.SLIDE.tsx`・二重サフィックス・`.slide.test.tsx` は黙って通常ページになる
+- default export は `<SlideDeck>` をルートに返す。フレームワークは包まない
+- `<Slide>` は `<SlideDeck>` の直接の子(配列は可。Fragment・自作コンポーネントで包まない)
+- `<Step>` は `<Steps>` の直接の子(包むと常に表示される)
+- スライドの部品は `@squadbase/vantage/slide` から import する
+
+**SHOULD**
+
+- 1 ファイル = 1 デッキ。ヘルパーコンポーネント・定数も同じ `.slide.tsx` に書く
+- 各 `<Slide>` のルート要素は `width: "100%"; height: "100%"` でキャンバスを埋める
+- canvas に描くチャート(`EChart`)は `data-waitfor="canvas"` で包む(無いと pptx でそのスライドが白紙になりうる)
+- pptx に出る中身をアプリの Context(router / query / テーマ)に依存させない
+- `MorphElement` の `id` はページ内で一意にし、入れ子にしない。遷移先の `<Slide>` で `transition.morph` を有効にする
+- pptx 用などの依存を追加しない(html-to-image / fflate は自動で入る)

package/theme.css

@@ -1,3 +1,7 @@
+/* GENERATED by scripts/gen-theme.mjs — do not edit. Sources:
+ *   packages/squadkit/registry/theme/theme.css (UI part tokens)
+ *   packages/squadkit/theme/slide-doc.css         (slide / document styles) */
+
 /**
  * Vantage design tokens. Imported after `@import "tailwindcss"` by the
  * generated runtime.css. Defines CSS variables (light + dark), maps them to
@@ -18,123 +22,154 @@
      `<select>` popup. */
   color-scheme: light;
 
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
+  --background: oklch(0.975 0.004 255);
+  --foreground: oklch(0.21 0.02 260);
   --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
+  --card-foreground: oklch(0.21 0.02 260);
   --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.21 0.02 260);
+  --primary: oklch(0.55 0.2 262);
   --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
+  --secondary: oklch(0.965 0.005 255);
+  --secondary-foreground: oklch(0.25 0.02 260);
+  --muted: oklch(0.965 0.005 255);
+  --muted-foreground: oklch(0.5 0.02 258);
+  --accent: oklch(0.955 0.01 255);
+  --accent-foreground: oklch(0.25 0.02 260);
+  --destructive: oklch(0.53 0.21 27.325);
   --destructive-foreground: oklch(0.985 0 0);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
-  --radius: 0.625rem;
-
-  --chart-1: hsl(221 83% 53%);
-  --chart-2: hsl(160 60% 45%);
-  --chart-3: hsl(31 90% 55%);
-  --chart-4: hsl(280 65% 60%);
-  --chart-5: hsl(340 75% 55%);
-
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.145 0 0);
-  --sidebar-primary: oklch(0.205 0 0);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.97 0 0);
-  --sidebar-accent-foreground: oklch(0.205 0 0);
-  --sidebar-border: oklch(0.922 0 0);
-  --sidebar-ring: oklch(0.708 0 0);
-
-  /* Slides (@squadbase/vantage/slide).
-     These are aliases, not values. Custom properties resolve lazily, so
-     pointing them at the tokens above is enough for a deck to follow `.dark`
-     and `[data-theme="dark"]` on its own — restating them in the dark block
-     below would create two places to keep in step for no gain. A deck
-     overrides any of them inline through `<SlideDeck theme>`. */
-  --slide-bg: var(--background);
-  --slide-fg: var(--foreground);
-  --slide-accent: var(--primary);
-  --slide-muted: var(--muted-foreground);
-  --slide-radius: var(--radius);
-  /* A system stack that includes Japanese. The pptx export rasterises through
-     an SVG `foreignObject`, where locally installed families resolve by name
-     but webfonts must be inlined — so a system default is what makes the
-     common path export correctly with nothing embedded. */
-  --slide-font-display:
-    system-ui, -apple-system, "Hiragino Kaku Gothic ProN", "Hiragino Sans", "Yu Gothic", Meiryo,
+  --border: oklch(0.93 0.006 255);
+  --input: oklch(0.9 0.01 255);
+  --ring: oklch(0.7 0.12 262);
+  --radius: 0.5rem;
+
+  /* Card elevation: a hairline-soft shadow in light, none in dark (the border does the work there). */
+  --shadow-card: 0 1px 2px 0 oklch(0.2 0.02 260 / 0.06);
+
+  /* Body typeface: a system stack only (no web font is shipped). Presets may swap
+     it; `@theme inline` below points `font-sans` at this variable, so overriding
+     the variable also moves the utility (and the `html` rule in `@layer base`).
+     Latin system faces carry no kana/kanji, so without Japanese families here the
+     browser picks a per-locale fallback (lang="en" -> e.g. thin "Yu Gothic" Regular
+     on Windows, or a face without a 500 weight on macOS) and kana render thin.
+     List the Japanese system faces explicitly, after the Latin ones, and keep
+     `ui-sans-serif` / `system-ui` behind them: on Japanese Windows both resolve to
+     the menu font, Yu Gothic UI, which is condensed (made to avoid UI resizing)
+     and has kana, so it would take the kana before Meiryo is ever reached.
+     `-apple-system` is Safari/Firefox; Chrome on macOS needs `BlinkMacSystemFont`. */
+  --font-sans:
+    -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-body: var(--slide-font-display);
-  /* Canvas pixels, on the 1920x1080 canvas — not rem: a slide is scaled as a
-     whole, so its type must not also follow the browser's root font size. */
-  --slide-size-hero: 168px;
-  --slide-size-body: 36px;
 
-  /* Documents (@squadbase/vantage/doc). Aliases, like --slide-*: they follow
-     `.dark` through the tokens they point at, so they are not restated in the
-     dark block. A document overrides any of them inline through
-     `<Document theme>`, an app through its styles.css. */
-  --doc-fg: var(--foreground);
-  --doc-muted: var(--muted-foreground);
-  --doc-accent: var(--primary);
-  --doc-border: var(--border);
-  --doc-subtle: var(--muted);
-  --doc-font-body: inherit;
-  --doc-font-heading: var(--doc-font-body);
-  --doc-font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-  --doc-size-body: 1rem;
-  --doc-line-height: 1.8;
-  --doc-max-width: 48rem;
+  --chart-1: oklch(0.55 0.2 262);
+  --chart-2: oklch(0.62 0.17 118);
+  --chart-3: oklch(0.5 0.19 352);
+  --chart-4: oklch(0.62 0.1 195);
+  --chart-5: oklch(0.44 0.18 300);
+
+  /* Semantic status tokens — see the contract above the `@theme inline` block. */
+  --positive: oklch(0.52 0.14 150);
+  --positive-subtle: oklch(0.96 0.04 150);
+  --negative: oklch(0.53 0.19 25);
+  --negative-subtle: oklch(0.96 0.03 25);
+  --warning: oklch(0.53 0.12 70);
+  --warning-subtle: oklch(0.96 0.05 85);
+  --info: oklch(0.52 0.16 255);
+  --info-subtle: oklch(0.96 0.03 250);
+  --positive-fill: oklch(0.62 0.15 150);
+  --negative-fill: oklch(0.62 0.17 25);
+  --warning-fill: oklch(0.79 0.16 82);
+  --info-fill: oklch(0.62 0.15 250);
+  --neutral-fill: oklch(0.62 0 0);
+  --neutral: oklch(0.52 0 0);
+  --neutral-subtle: oklch(0.96 0 0);
+
+  --sidebar: oklch(0.985 0.003 255);
+  --sidebar-foreground: oklch(0.21 0.02 260);
+  --sidebar-primary: oklch(0.55 0.2 262);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.955 0.01 255);
+  --sidebar-accent-foreground: oklch(0.25 0.02 260);
+  --sidebar-border: oklch(0.915 0.008 255);
+  --sidebar-ring: oklch(0.7 0.12 262);
 }
 
 .dark,
 [data-theme="dark"] {
   color-scheme: dark;
 
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.205 0 0);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.205 0 0);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.922 0 0);
-  --primary-foreground: oklch(0.205 0 0);
-  --secondary: oklch(0.269 0 0);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.269 0 0);
-  --muted-foreground: oklch(0.708 0 0);
-  --accent: oklch(0.269 0 0);
-  --accent-foreground: oklch(0.985 0 0);
+  --shadow-card: none;
+
+  --background: oklch(0.16 0.012 262);
+  --foreground: oklch(0.96 0.005 255);
+  --card: oklch(0.215 0.015 262);
+  --card-foreground: oklch(0.96 0.005 255);
+  --popover: oklch(0.235 0.016 262);
+  --popover-foreground: oklch(0.96 0.005 255);
+  --primary: oklch(0.68 0.19 262);
+  --primary-foreground: oklch(0.145 0.02 262);
+  --secondary: oklch(0.27 0.016 262);
+  --secondary-foreground: oklch(0.96 0.005 255);
+  --muted: oklch(0.27 0.016 262);
+  --muted-foreground: oklch(0.72 0.02 258);
+  --accent: oklch(0.3 0.02 262);
+  --accent-foreground: oklch(0.96 0.005 255);
   --destructive: oklch(0.704 0.191 22.216);
-  --destructive-foreground: oklch(0.985 0 0);
+  --destructive-foreground: oklch(0.145 0.02 262);
   --border: oklch(1 0 0 / 10%);
   --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.556 0 0);
-
-  --chart-1: hsl(217 91% 60%);
-  --chart-2: hsl(160 60% 45%);
-  --chart-3: hsl(31 90% 55%);
-  --chart-4: hsl(280 65% 65%);
-  --chart-5: hsl(340 75% 60%);
-
-  --sidebar: oklch(0.205 0 0);
-  --sidebar-foreground: oklch(0.985 0 0);
-  --sidebar-primary: oklch(0.488 0.243 264.376);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.269 0 0);
-  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --ring: oklch(0.6 0.15 262);
+
+  --chart-1: oklch(0.56 0.19 262);
+  --chart-2: oklch(0.75 0.17 118);
+  --chart-3: oklch(0.64 0.19 352);
+  --chart-4: oklch(0.78 0.105 195);
+  --chart-5: oklch(0.71 0.17 300);
+
+  --positive: oklch(0.76 0.15 150);
+  --positive-subtle: oklch(0.27 0.05 150);
+  --negative: oklch(0.74 0.15 22);
+  --negative-subtle: oklch(0.27 0.06 25);
+  --warning: oklch(0.8 0.14 80);
+  --warning-subtle: oklch(0.27 0.05 75);
+  --info: oklch(0.75 0.12 250);
+  --info-subtle: oklch(0.27 0.06 255);
+  --positive-fill: oklch(0.56 0.13 150);
+  --negative-fill: oklch(0.56 0.15 22);
+  --warning-fill: oklch(0.73 0.145 78);
+  --info-fill: oklch(0.56 0.13 250);
+  --neutral-fill: oklch(0.56 0 0);
+  --neutral: oklch(0.85 0 0);
+  --neutral-subtle: oklch(0.27 0 0);
+
+  --sidebar: oklch(0.2 0.014 262);
+  --sidebar-foreground: oklch(0.96 0.005 255);
+  --sidebar-primary: oklch(0.68 0.19 262);
+  --sidebar-primary-foreground: oklch(0.145 0.02 262);
+  --sidebar-accent: oklch(0.3 0.02 262);
+  --sidebar-accent-foreground: oklch(0.96 0.005 255);
   --sidebar-border: oklch(1 0 0 / 10%);
-  --sidebar-ring: oklch(0.556 0 0);
+  --sidebar-ring: oklch(0.6 0.15 262);
 }
 
+/* Semantic status tokens (increase/decrease/status). Every increase, decrease
+   and status colour in registry/ comes from these — never a Tailwind palette
+   colour like `green-500` (tests/raw-colors.test.ts enforces it).
+     --<tone>         text colour on --background, --card and --<tone>-subtle
+                      (>= 4.5:1), and dot / line / icon colour (>= 3:1).
+     --<tone>-subtle  tinted background behind --<tone> text (badges, callouts).
+     --<tone>-fill   (incl. --neutral-fill, the grey area) FILL colour for areas (bars, heatmap cells, tracker blocks). Not for
+                      text or icons — use --<tone>. Same lightness step from the page in both
+                      modes (light 0.62 / dark 0.56: ~0.36-0.40 OKLCH L away from --background,
+                      >= 3:1 against --background and --card), so a fill is never strong in one
+                      mode and faint in the other. Presets may tune hue and chroma within the
+                      status bands while preserving contrast and fill strength (tests/theme-presets.test.ts).
+                      --warning-fill is the exception: amber (light 0.79 / dark 0.73, ~#f5b324 / ~#d99a1e) is
+                      a light colour by nature, so it is ~2:1 on the light page (still >= 0.18 L away)
+                      and ~7-8:1 on the dark one; dark text (--foreground in light, --background in dark) sits on it at >= 4.5:1.
+   Tones: positive (green), negative (red), warning (amber), info (blue),
+   neutral (grey). Colour never carries the meaning alone — pair it with an
+   arrow or sign. `npm run contrast` prints the measured ratios. */
 @theme inline {
   --color-background: var(--background);
   --color-foreground: var(--foreground);
@@ -155,6 +190,21 @@
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
+  --color-positive: var(--positive);
+  --color-positive-subtle: var(--positive-subtle);
+  --color-negative: var(--negative);
+  --color-negative-subtle: var(--negative-subtle);
+  --color-warning: var(--warning);
+  --color-warning-subtle: var(--warning-subtle);
+  --color-info: var(--info);
+  --color-info-subtle: var(--info-subtle);
+  --color-positive-fill: var(--positive-fill);
+  --color-negative-fill: var(--negative-fill);
+  --color-warning-fill: var(--warning-fill);
+  --color-info-fill: var(--info-fill);
+  --color-neutral-fill: var(--neutral-fill);
+  --color-neutral: var(--neutral);
+  --color-neutral-subtle: var(--neutral-subtle);
   --color-chart-1: var(--chart-1);
   --color-chart-2: var(--chart-2);
   --color-chart-3: var(--chart-3);
@@ -168,10 +218,7 @@
   --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
   --color-sidebar-border: var(--sidebar-border);
   --color-sidebar-ring: var(--sidebar-ring);
-  --color-slide-bg: var(--slide-bg);
-  --color-slide-fg: var(--slide-fg);
-  --color-slide-accent: var(--slide-accent);
-  --color-slide-muted: var(--slide-muted);
+  --font-sans: var(--font-sans);
   --radius-sm: calc(var(--radius) - 4px);
   --radius-md: calc(var(--radius) - 2px);
   --radius-lg: var(--radius);
@@ -272,6 +319,100 @@
   }
 }
 
+/* ------------------------------------------------------------ utilities */
+
+@utility no-scrollbar {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+
+/* Icons that must point the other way when the document is right-to-left. */
+.cn-rtl-flip {
+  &:where([dir="rtl"], [dir="rtl"] *) {
+    transform: scaleX(-1);
+  }
+}
+
+/* Page defaults live in `@layer base`, like shadcn's own init, so a project's
+   `html { @apply font-sans }`, its `next/font` setup and its own border rules
+   (all unlayered or later in the layer) win over them instead of losing to an
+   unlayered rule here. */
+@layer base {
+  html {
+    font-family: var(--font-sans);
+  }
+
+  body {
+    background-color: var(--background);
+    color: var(--foreground);
+    -webkit-font-smoothing: antialiased;
+  }
+
+  * {
+    border-color: var(--border);
+  }
+}
+
+/**
+ * Vantage framework styles: the slide / document tokens and the document
+ * typesetting. The UI parts' tokens live in SquadKit
+ * (packages/squadkit/registry/theme/theme.css); packages/vantage/scripts/gen-theme.mjs
+ * appends this file to them to produce packages/vantage/theme.css.
+ */
+
+:root {
+  /* Slides (@squadbase/vantage/slide).
+     These are aliases, not values. Custom properties resolve lazily, so
+     pointing them at the tokens above is enough for a deck to follow `.dark`
+     and `[data-theme="dark"]` on its own — restating them in the dark block
+     below would create two places to keep in step for no gain. A deck
+     overrides any of them inline through `<SlideDeck theme>`. */
+  --slide-bg: var(--background);
+  --slide-fg: var(--foreground);
+  --slide-accent: var(--primary);
+  --slide-muted: var(--muted-foreground);
+  --slide-radius: var(--radius);
+  /* A system stack that includes Japanese. The pptx export rasterises through
+     an SVG `foreignObject`, where locally installed families resolve by name
+     but webfonts must be inlined — so a system default is what makes the
+     common path export correctly with nothing embedded. */
+  --slide-font-display:
+    -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);
+  /* Canvas pixels, on the 1920x1080 canvas — not rem: a slide is scaled as a
+     whole, so its type must not also follow the browser's root font size. */
+  --slide-size-hero: 168px;
+  --slide-size-body: 36px;
+
+  /* Documents (@squadbase/vantage/doc). Aliases, like --slide-*: they follow
+     `.dark` through the tokens they point at, so they are not restated in the
+     dark block. A document overrides any of them inline through
+     `<Document theme>`, an app through its styles.css. */
+  --doc-fg: var(--foreground);
+  --doc-muted: var(--muted-foreground);
+  --doc-accent: var(--primary);
+  --doc-border: var(--border);
+  --doc-subtle: var(--muted);
+  --doc-font-body: inherit;
+  --doc-font-heading: var(--doc-font-body);
+  --doc-font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --doc-size-body: 1rem;
+  --doc-line-height: 1.8;
+  --doc-max-width: 48rem;
+}
+
+@theme inline {
+  --color-slide-bg: var(--slide-bg);
+  --color-slide-fg: var(--slide-fg);
+  --color-slide-accent: var(--slide-accent);
+  --color-slide-muted: var(--slide-muted);
+}
+
 /* ------------------------------------------------------------ documents */
 
 /* Typesetting for `<Document>`. Plain elements inside it need no classes.
@@ -287,17 +428,6 @@
     line-height: var(--doc-line-height);
     overflow-wrap: break-word;
   }
-  /* On screen the document sits in the app frame's unpadded `<main>`, so it
-     brings its own gutter. `content-box` keeps `--doc-max-width` the width of
-     the text: the side gutter shows only once the frame is narrower than that.
-     The bottom leaves room for the fixed "Save as PDF" button. Paper takes its
-     margin from the print rules below instead. */
-  @media screen {
-    :where([data-slot="document"]) {
-      box-sizing: content-box;
-      padding: 3rem 1.5rem 5rem;
-    }
-  }
   :where([data-slot="document"]) :where(h1, h2, h3, h4) {
     font-family: var(--doc-font-heading);
     font-weight: 700;
@@ -451,38 +581,3 @@
     overflow: visible;
   }
 }
-
-/* ------------------------------------------------------------ utilities */
-
-@utility no-scrollbar {
-  -ms-overflow-style: none;
-  scrollbar-width: none;
-
-  &::-webkit-scrollbar {
-    display: none;
-  }
-}
-
-/* Icons that must point the other way when the document is right-to-left. */
-.cn-rtl-flip {
-  &:where([dir="rtl"], [dir="rtl"] *) {
-    transform: scaleX(-1);
-  }
-}
-
-body {
-  background-color: var(--background);
-  color: var(--foreground);
-  /* Latin system faces carry no kana/kanji, so without Japanese families here the
-     browser picks a per-locale fallback (lang="en" → e.g. thin "Yu Gothic" Regular
-     on Windows, or a face without a 500 weight on macOS) and kana render thin.
-     List the Japanese system faces explicitly, after the Latin ones. */
-  font-family:
-    ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Hiragino Sans", "Hiragino Kaku Gothic ProN", "Noto Sans JP", "Yu Gothic UI", Meiryo,
-    sans-serif;
-  -webkit-font-smoothing: antialiased;
-}
-
-* {
-  border-color: var(--border);
-}