@squadbase/vantage 0.6.0-dev.3cc6138 → 0.6.1-dev.2d25e94

package/docs/en/agent-skills.md

@@ -15,6 +15,7 @@ All of these target an agent that is **building a Vantage app**.
 | `vantage-app` | Creating an app, and growing a single-file `index.tsx` SPA into a fullstack app with `server/api`, nested layouts, dynamic routes, and 404/error pages |
 | `vantage-add-feature` | Adding a page / API / UI / block (`vantage add` through to `check` / `routes`) |
 | `vantage-slide` | Writing a slide deck in `.slide.tsx` (the 1920×1080 canvas's vertical budget, the type scale, stepped reveals, transitions and morph, what a pptx export needs) |
+| `vantage-design` | Creating / updating `DESIGN.md` (the design intent) and `styles.css` (the values) together — colors, chart palette, fonts, matching a brand from a URL, logo, document, or an external DESIGN.md, and checking contrast |
 | `vantage-pitfalls` | A pitfalls reference (Base UI ≠ Radix, `SelectValue` behavior, never importing `server/` from the client, and more) |
 | `project-storage` | Working with Squadbase Project Storage (uploaded files) from the browser — listing, embedding images / video / PDFs, uploading. For apps running on Squadbase |
 
@@ -42,6 +43,7 @@ Bundled skills:
   project-storage      .claude/skills/project-storage/
   vantage-add-feature  .claude/skills/vantage-add-feature/
   vantage-app          .claude/skills/vantage-app/
+  vantage-design       not placed
   vantage-pitfalls     not placed
   vantage-slide        not placed
 ```
@@ -60,6 +62,7 @@ your-app/
     └── skills/
         ├── vantage-app/SKILL.md
         ├── vantage-add-feature/SKILL.md
+        ├── vantage-design/SKILL.md     (its references/ and scripts/ ride along)
         ├── vantage-pitfalls/SKILL.md
         ├── vantage-slide/SKILL.md      (its references/ ride along)
         └── project-storage/SKILL.md

package/docs/en/changelog.md

@@ -9,6 +9,30 @@ What changed in each Vantage release. Newest is on top.
 > minor release may include backwards-incompatible changes. A patch is limited to
 > backwards-compatible additions and bug fixes.
 
+## v0.6.2
+
+The dev server can now run behind a reverse proxy (2026-09-23).
+
+### Added
+
+- **`--host [addr]` and `--allowed-hosts <list|true>`** on `vantage dev` / SPA `vantage preview`.
+  Vite rejects with 403 any request whose `Host` header is not `localhost`, so anything with
+  **another hostname in front of the server** — a sandbox preview proxy, a tunnel — could not reach
+  it before. `--allowed-hosts` can also come from the **`VANTAGE_ALLOWED_HOSTS`** environment
+  variable (the flag wins). With neither, nothing changes. See the
+  [CLI reference](cli-reference).
+
+## v0.6.1
+
+Pages can now be written as documents (2026-09-25).
+
+### Added
+
+- **`<name>.doc.tsx` becomes a document page.** Wrap it in `Document` from
+  `@squadbase/vantage/doc` and the headings, paragraphs, lists, tables, quotes and code inside are
+  styled with no classes. Colour, type and column width come from the `--doc-*` tokens. See
+  [Routing](routing) and [UI & theming](ui-and-theming).
+
 ## v0.6.0
 
 What you can drop in `src/` is no longer just `.tsx`. A `.csv` or `.xlsx` becomes a page you can
@@ -78,6 +102,12 @@ your dashboard pages.
   set (`AGENTS.md` + `agents/`) into the app root, and `vantage upgrade` re-syncs it (files not
   in the bundle are never deleted).
 
+- **`DESIGN.md` and a `vantage-design` skill.** Describe the design intent (color roles, charts,
+  type, layout) by token name in a `DESIGN.md` at the project root, and agents read it before
+  writing any UI (`AGENTS.md` / `agents/page.md` / `agents/slide.md` now point to it).
+  `DESIGN.md` belongs to you — `vantage upgrade` never touches it. Requests like "match our brand"
+  go through the `vantage-design` skill, which updates `DESIGN.md` and `styles.css` together.
+
 ### Changed
 
 - The `RouteInfo` returned by `useRoutes()` gained **`kind`** (`"module"` | `"file"`) and

package/docs/en/cli-reference.md

@@ -357,6 +357,36 @@ vantage dev --strict-port                  # will not start unless 5173 is free
 > default silently. A fullstack `preview` binds its Node server to exactly one port, so it is **always**
 > strict and `--no-strict-port` has no effect there.
 
+## `--host` / `--allowed-hosts` — running behind a reverse proxy
+
+By default `vantage dev` and a SPA `vantage preview` bind to `localhost` only and **reject with 403**
+any request whose `Host` header is not `localhost` or the bound address (Vite's DNS-rebinding
+protection). When something with **another hostname** sits in front of the server — a sandbox
+preview proxy, a tunnel, a container network — these two flags let it through.
+
+```bash
+vantage dev --host                              # listen on every interface
+vantage dev --host 0.0.0.0                      # or on one address (--host=:: works too)
+vantage dev --allowed-hosts preview.example.com # allow the hostname the proxy presents (comma-separated for several)
+vantage dev --allowed-hosts true                # disable the Host check altogether
+```
+
+| Flag | Meaning |
+|---|---|
+| `--host [addr]` | Without a value, bind to **every interface**; with one, bind to that address (Vite's `server.host`) |
+| `--allowed-hosts <list\|true>` | The `Host` headers to accept, comma-separated. `true` disables the check (Vite's `server.allowedHosts`) |
+
+`--allowed-hosts` can also come from the environment variable **`VANTAGE_ALLOWED_HOSTS`** (same
+format), which suits a supervisor that starts the server and knows the hostname. When both are
+present, **the flag wins**. With neither, Vite's default applies and only `localhost` is accepted,
+exactly as before.
+
+> [!NOTE]
+> `--host` takes the next token as its value, so `vantage --host dev` would read `dev` as the
+> address — write `--host=<addr>` or put `--host` last when a command or path follows it. A fullstack
+> `preview` runs the Node server, which listens on every interface and does no `Host` check, so
+> neither flag has an effect there (the command says so).
+
 ## Browser output in dev — forwarding and the overlay
 
 `vantage dev` **forwards what happens in the browser to the dev terminal**. By default that means
@@ -418,7 +448,7 @@ phases are `scan` (route discovery), `diagnostics` (the static checks),
 
 ## Static diagnostics (`check`)
 
-`vantage check` detects these eleven diagnostics (seven errors, four warnings).
+`vantage check` detects these thirteen diagnostics (seven errors, six warnings).
 
 | Code | Severity | Meaning |
 |---|---|---|
@@ -433,9 +463,13 @@ phases are `scan` (route discovery), `diagnostics` (the static checks),
 | `PUBLIC_ENV_MISUSE` | warning | Client reads a non-`PUBLIC_` env variable |
 | `UNSUPPORTED_PAGE_FILE` | warning | A file with an extension Vantage has no viewer for (`.xls`, `.ods`, …); it does not become a route |
 | `FILE_PAGE_TOO_LARGE` | warning | A data-file page is over 25 MB, so it will render an error instead of a table |
+| `HARDCODED_COLOR` | warning | A `.ts`/`.tsx` file hard-codes a color (`#hex`, `rgb()`/`hsl()`/`oklch()`, …, `bg-[#…]`, or a Tailwind palette class like `bg-blue-500`); reported per file as `path:line` with a suggested token |
+| `DESIGN_MD_TOO_LONG` | warning | The root `DESIGN.md` is over 150 lines; keep values in `styles.css` and reference them by token name |
 
 None of them import or run your code — the checks are purely static.
 
+`HARDCODED_COLOR` never reads `.css` (`styles.css` is where values belong). When a color carries data meaning (map fills, say), put `// vantage-ignore-color` (`{/* vantage-ignore-color */}` inside JSX) on that line or the line above it; `vantage-ignore-color-file` within the first five lines exempts the whole file.
+
 ## Build output
 
 Inside `dist/`:

package/docs/en/routing.md

@@ -1,6 +1,6 @@
 # File-based routing
 
-> Dropping a file creates a route. Conventions for pages, layouts, dynamic params and 404/error, plus the pages that are not .tsx (csv / xlsx / slides).
+> Dropping a file creates a route. Conventions for pages, layouts, dynamic params and 404/error, plus the pages that are not .tsx (csv / xlsx / slides / documents).
 
 In Vantage, **where you place a file is its URL**. You never configure a router.
 
@@ -37,6 +37,7 @@ The "File" column below is relative to the page-scan root above.
 | `_404.tsx` | Not-found UI (**root only**) |
 | `_error.tsx` | Error UI (**root only**) |
 | `monthly-report.slide.tsx` | `/monthly-report` (a slide deck) |
+| `june-summary.doc.tsx` | `/june-summary` (a document) |
 | `sales-export.csv` | `/sales-export` (drawn as a table) |
 | `data/june.xlsx` | `/data/june` (same) |
 
@@ -47,8 +48,8 @@ The "File" column below is relative to the page-scan root above.
 ## Pages that are not `.tsx`
 
 Routes do not come only from `.tsx` / `.jsx`. **`.csv` and `.xlsx`** become pages you can read as a
-table, and **`<name>.slide.tsx`** becomes a slide deck. Both build their URL exactly the way a
-`.tsx` page does, and both appear in `vantage routes` and in a `useRoutes()` nav alongside it.
+table, **`<name>.slide.tsx`** becomes a slide deck, and **`<name>.doc.tsx`** becomes a document. All
+of them build their URL exactly the way a `.tsx` page does, and all appear in `vantage routes` and in a `useRoutes()` nav alongside it.
 
 ### Data files (`.csv` / `.xlsx`)
 
@@ -109,6 +110,32 @@ deck as a pptx. See
 > `deck.slide.ts` raise `INVALID_PAGE_VARIANT`. And since `june.slide.tsx` and `june.tsx` — like
 > `sales.csv` and `sales.tsx` — resolve to the same URL, having both is a `ROUTE_CONFLICT`.
 
+### Documents (`.doc.tsx`)
+
+`.doc` is a **page-kind suffix** too (`src/june-summary.doc.tsx` → `/june-summary`). A document is
+prose read top to bottom; the file is an ordinary React component returning a `<Document>`.
+
+```tsx
+import { definePage } from "@squadbase/vantage";
+import { Document } from "@squadbase/vantage/doc";
+
+export const page = definePage({ title: "June summary" });
+
+export default function JuneSummary() {
+  return (
+    <Document>
+      <h1>June summary</h1>
+      <p>June revenue came in 5% above target.</p>
+      <table>…</table>
+    </Document>
+  );
+}
+```
+
+Headings, paragraphs, lists, tables, quotes and code inside `<Document>` are styled with no classes
+written. See [UI & theming](ui-and-theming). As with `.slide`, only a page module that becomes a
+route may carry `.doc`.
+
 ## Directories that are never routed
 
 These directories are never scanned, at any depth. Put whatever code you like here.
@@ -219,7 +246,7 @@ Each entry is a `RouteInfo`:
 | `label` | `string` | Display name: `navLabel`, else `title`, else `path` |
 | `title` / `description` / `navLabel` | `string \| undefined` | Values from [`definePage`](pages-and-metadata) |
 | `kind` | `"module" \| "file"` | What the page is drawn from; `"file"` is a `.csv` / `.xlsx` |
-| `variant` | `"slide" \| undefined` | The page-kind suffix the file carried |
+| `variant` | `"slide" \| "doc" \| undefined` | The page-kind suffix the file carried |
 
 `useCurrentRoute()` returns the route being rendered, or `undefined` on the 404 route. Beyond the
 "you are here" check above, it fits breadcrumbs and page headings.

package/docs/en/ui-and-theming.md

@@ -116,6 +116,32 @@ behind transitions, the rules morph rests on, and what breaks a pptx export —
 > Tailwind for dashboards, so projecting a scaled 1920×1080 canvas leaves a `text-sm` button at an
 > effective 8px — unreadable.
 
+## Documents (`/doc`)
+
+A `<name>.doc.tsx` [becomes a document page](routing). Wrap it in `Document` and the plain HTML
+elements written inside (`h1`–`h4`, `p`, `ul`/`ol`, `table`, `blockquote`, `pre`/`code`, `hr`, `a`,
+`figure`/`figcaption`, `img`) get their heading sizes, spacing and rules. A
+[`EChart`](parts/echart) can sit in the text as it is.
+
+```tsx
+import { Document } from "@squadbase/vantage/doc";
+```
+
+Colour, type and the width of the text column are `--doc-*` tokens. By default they alias the app's
+tokens, so **they follow dark mode on their own**.
+
+| Token | Default | What it styles |
+|---|---|---|
+| `--doc-fg` / `--doc-muted` | `--foreground` / `--muted-foreground` | Body text / quotes and captions |
+| `--doc-accent` | `--primary` | Links |
+| `--doc-border` / `--doc-subtle` | `--border` / `--muted` | Rules / background of code and table headers |
+| `--doc-font-body` / `--doc-font-heading` / `--doc-font-mono` | The app's type | Body / headings / code |
+| `--doc-size-body` / `--doc-line-height` / `--doc-max-width` | `1rem` / `1.8` / `48rem` | Type size / line height / column width |
+
+Override them app-wide on `:root` in `styles.css`, or for one document with
+`<Document theme={{ accent: "#2563eb" }}>`. A Tailwind utility on an element through `className`
+wins over the default styling.
+
 ## Tailwind just works
 
 Write Tailwind utilities in `className` and they apply. You never write `tailwind.config` or

package/docs/index.json

@@ -28,7 +28,7 @@
       "section": "guide",
       "sectionTitle": "ガイド",
       "title": "ファイルベースルーティング",
-      "description": "ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約と、tsx 以外のページ（csv / xlsx / スライド）。",
+      "description": "ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約と、tsx 以外のページ（csv / xlsx / スライド / ドキュメント）。",
       "file": "ja/routing.md",
       "order": 1
     },
@@ -720,7 +720,7 @@
       "section": "guide",
       "sectionTitle": "Guide",
       "title": "File-based routing",
-      "description": "Dropping a file creates a route. Conventions for pages, layouts, dynamic params and 404/error, plus the pages that are not .tsx (csv / xlsx / slides).",
+      "description": "Dropping a file creates a route. Conventions for pages, layouts, dynamic params and 404/error, plus the pages that are not .tsx (csv / xlsx / slides / documents).",
       "file": "en/routing.md",
       "order": 1
     },

package/docs/ja/agent-skills.md

@@ -15,6 +15,7 @@ Vantage は **Claude Code の Agent Skills** を同梱しています。Skill
 | `vantage-app` | アプリの新規作成と、`index.tsx` 単体の SPA から `server/api`・ネストレイアウト・動的ルート・404/error を備えた fullstack への拡張 |
 | `vantage-add-feature` | ページ / API / UI / ブロックの追加(`vantage add` + `check` / `routes` までの一連) |
 | `vantage-slide` | `.slide.tsx` でスライドデッキを書く(1920×1080 キャンバスの縦方向の予算、タイプスケール、段階表示、トランジションとモーフ、pptx 書き出しの前提) |
+| `vantage-design` | 見た目の意図 `DESIGN.md` と値を持つ `styles.css` をまとめて作る / 更新する(配色・チャートの色・書体・ブランド合わせ。URL・ロゴ・資料・外部の DESIGN.md からの取り込み、コントラストの確認) |
 | `vantage-pitfalls` | 落とし穴リファレンス(Base UI ≠ Radix、`SelectValue` の挙動、クライアントから `server/` を import しない など) |
 | `project-storage` | Squadbase の Project Storage(アップロード済みファイル)をブラウザから扱う(一覧、画像 / 動画 / PDF の埋め込み、アップロード)。Squadbase 上で動くアプリ向け |
 
@@ -42,6 +43,7 @@ Bundled skills:
   project-storage      .claude/skills/project-storage/
   vantage-add-feature  .claude/skills/vantage-add-feature/
   vantage-app          .claude/skills/vantage-app/
+  vantage-design       not placed
   vantage-pitfalls     not placed
   vantage-slide        not placed
 ```
@@ -60,6 +62,7 @@ your-app/
     └── skills/
         ├── vantage-app/SKILL.md
         ├── vantage-add-feature/SKILL.md
+        ├── vantage-design/SKILL.md     (references/ と scripts/ も一緒に配られる)
         ├── vantage-pitfalls/SKILL.md
         ├── vantage-slide/SKILL.md      (references/ も一緒に配られる)
         └── project-storage/SKILL.md

package/docs/ja/changelog.md

@@ -8,6 +8,30 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
 > まだプロトタイプ(**0.x**)です。0.x の間は **minor が実質のメジャー**扱いで、後方互換性の
 > ない変更は minor で入ることがあります。patch は後方互換の機能追加とバグ修正のみです。
 
+## v0.6.2
+
+リバースプロキシの後ろで dev サーバーを動かせるようになりました(2026-09-23)。
+
+### 追加
+
+- **`--host [addr]` と `--allowed-hosts <list|true>`** を `vantage dev` / `vantage preview`(SPA)に
+  追加しました。Vite は `Host` ヘッダが `localhost` 以外のリクエストを 403 で拒否するため、
+  サンドボックスのプレビュープロキシやトンネルなど**別のホスト名で前に立つもの**があると
+  そのままでは届きませんでした。`--allowed-hosts` は環境変数 **`VANTAGE_ALLOWED_HOSTS`** でも
+  渡せます(フラグが優先)。どちらも指定しなければ挙動は従来どおりです。詳細は
+  [CLI リファレンス](cli-reference)を参照してください。
+
+## v0.6.1
+
+ドキュメントのページを書けるようになりました(2026-09-25)。
+
+### 追加
+
+- **`<name>.doc.tsx` がドキュメントのページになります。** `@squadbase/vantage/doc` の `Document` で
+  包むと、中の見出し・段落・リスト・表・引用・コードにクラスなしでスタイルが当たります。配色・書体・
+  本文の幅は `--doc-*` トークンで変えられます。詳しくは[ルーティング](routing)と
+  [UI とテーマ](ui-and-theming)を参照してください。
+
 ## v0.6.0
 
 `src/` に置けるものが `.tsx` だけではなくなりました。`.csv` / `.xlsx` はそのまま表として
@@ -75,6 +99,12 @@ Vantage のリリースごとの変更点です。新しいものが上に来ま
   減ります。`vantage add agents` はこのセット一式をアプリルート(`AGENTS.md` + `agents/`)へ
   配置し、`vantage upgrade` はまとめて再同期します(バンドルに無いファイルは消しません)。
 
+- **`DESIGN.md` と `vantage-design` skill を追加しました。** プロジェクトルートの `DESIGN.md` に
+  見た目の意図(配色の役割・チャート・書体・レイアウト)をトークン名で書いておくと、エージェントは
+  UI を書く前にそれを読みます(`AGENTS.md` / `agents/page.md` / `agents/slide.md` に案内を追加)。
+  `DESIGN.md` はユーザーの持ち物で、`vantage upgrade` は触りません。「ブランドに合わせて」などの
+  依頼は `vantage-design` skill が `DESIGN.md` と `styles.css` をまとめて更新します。
+
 ### 変更
 
 - `useRoutes()` が返す `RouteInfo` に **`kind`**(`"module"` | `"file"`)と

package/docs/ja/cli-reference.md

@@ -351,6 +351,35 @@ vantage dev --strict-port                  # 5173 が取れなければ起動し
 > また fullstack の `preview` は Node サーバーを 1 ポートに bind するだけなので**常に厳格**で、
 > `--no-strict-port` は効きません。
 
+## `--host` / `--allowed-hosts` — リバースプロキシの後ろで動かす
+
+`vantage dev` と `vantage preview`(SPA)は、既定では `localhost` にしか bind せず、`Host` ヘッダが
+`localhost` か bind したアドレス以外のリクエストを **403 で拒否**します(Vite の DNS リバインディング
+対策)。サンドボックスのプレビュープロキシ・トンネル・コンテナのネットワークなど、**別のホスト名で
+前に立つもの**があるときは、この 2 つを組み合わせて通します。
+
+```bash
+vantage dev --host                              # すべてのインターフェースで listen
+vantage dev --host 0.0.0.0                      # アドレスを明示(--host=:: の形も可)
+vantage dev --allowed-hosts preview.example.com # プロキシが名乗るホスト名を許可(カンマ区切りで複数)
+vantage dev --allowed-hosts true                # Host の検査そのものを無効化
+```
+
+| フラグ | 意味 |
+|---|---|
+| `--host [addr]` | 値なしなら**すべてのインターフェース**、値があればそのアドレスに bind する(Vite の `server.host`)|
+| `--allowed-hosts <list\|true>` | 受け付ける `Host` ヘッダの一覧(カンマ区切り)。`true` で検査を無効化(Vite の `server.allowedHosts`)|
+
+`--allowed-hosts` は環境変数 **`VANTAGE_ALLOWED_HOSTS`** でも渡せます(同じ書式)。サーバーを起動する
+側の仕組みがホスト名を知っている場合はそちらが便利です。フラグと環境変数の両方があれば**フラグが
+勝ちます**。どちらも無ければ Vite の既定のままで、これまでどおり `localhost` だけを受け付けます。
+
+> [!NOTE]
+> `--host` の値は次のトークンを取ります。`vantage --host dev` のように直後にコマンドやパスが来る
+> 書き方は値と取り違えるので、その場合は `--host=<addr>` か、末尾に `--host` を置いてください。
+> fullstack の `preview` は Node サーバーがすべてのインターフェースで listen し `Host` を検査しない
+> ので、どちらのフラグも効きません(その旨が表示されます)。
+
 ## dev のブラウザ出力 — 転送とオーバーレイ
 
 `vantage dev` は、ブラウザ側で起きたことを**開発ターミナルへ転送します**。既定で転送するのは
@@ -411,7 +440,7 @@ VANTAGE_PROFILE=1 vantage dev
 
 ## 静的診断（`check`）
 
-`vantage check` が検出する診断は次の 11 種類です（エラー 7・警告 4）。
+`vantage check` が検出する診断は次の 13 種類です（エラー 7・警告 6）。
 
 | コード | 深刻度 | 意味 |
 |---|---|---|
@@ -426,9 +455,13 @@ VANTAGE_PROFILE=1 vantage dev
 | `PUBLIC_ENV_MISUSE` | 警告 | クライアントが `PUBLIC_` 以外の env を読んでいる |
 | `UNSUPPORTED_PAGE_FILE` | 警告 | ビューアの無い拡張子（`.xls`・`.ods` など）を置いている。ルートにならない |
 | `FILE_PAGE_TOO_LARGE` | 警告 | データファイルページが 25MB を超えている。そのページはエラー表示になる |
+| `HARDCODED_COLOR` | 警告 | `.ts`/`.tsx` に色を直書きしている（`#hex`・`rgb()`/`hsl()`/`oklch()` など・`bg-[#…]`・`bg-blue-500` などの Tailwind パレット）。ファイルごとに `path:行` と置き換え候補のトークンを出す |
+| `DESIGN_MD_TOO_LONG` | 警告 | ルートの `DESIGN.md` が 150 行を超えている。実値は `styles.css` に置き、トークン名で参照する |
 
 いずれもユーザーコードを import・実行しません（純粋に静的な検査です）。
 
+`HARDCODED_COLOR` は `.css` を見ません（値の置き場は `styles.css`）。地図の塗り分けのように色がデータの意味を持つ場合は、その行か直前の行に `// vantage-ignore-color`（JSX 内は `{/* vantage-ignore-color */}`）を付けると除外されます。ファイルごと除外するには先頭 5 行以内に `vantage-ignore-color-file` を書きます。
+
 ## 生成物と成果物
 
 `dist/` の中身:

package/docs/ja/routing.md

@@ -1,6 +1,6 @@
 # ファイルベースルーティング
 
-> ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約と、tsx 以外のページ（csv / xlsx / スライド）。
+> ファイルを置くだけでルートが生まれる。ページ・レイアウト・動的パラメータ・404/error の規約と、tsx 以外のページ（csv / xlsx / スライド / ドキュメント）。
 
 Vantage のルーティングは **ファイルの配置がそのまま URL** になります。ルーターの設定は書きません。
 
@@ -36,6 +36,7 @@ Vantage のルーティングは **ファイルの配置がそのまま URL**
 | `_404.tsx` | not-found の UI（**ルートのみ**） |
 | `_error.tsx` | error の UI（**ルートのみ**） |
 | `monthly-report.slide.tsx` | `/monthly-report`（スライドデッキ） |
+| `june-summary.doc.tsx` | `/june-summary`（ドキュメント） |
 | `sales-export.csv` | `/sales-export`（表として描かれる） |
 | `data/june.xlsx` | `/data/june`（同上） |
 
@@ -46,7 +47,7 @@ Vantage のルーティングは **ファイルの配置がそのまま URL**
 ## tsx 以外もページになる
 
 ルートになるのは `.tsx` / `.jsx` だけではありません。**`.csv` と `.xlsx`** はそのまま表として
-読めるページになり、**`<name>.slide.tsx`** はスライドデッキになります。どちらも URL の作り方は
+読めるページになり、**`<name>.slide.tsx`** はスライドデッキに、**`<name>.doc.tsx`** はドキュメントになります。どれも URL の作り方は
 tsx と同じで、`vantage routes` にも `useRoutes()` のナビにも同格で並びます。
 
 ### データファイル（`.csv` / `.xlsx`）
@@ -104,6 +105,32 @@ export default function Deck() {
 > `deck.slide.ts` は `INVALID_PAGE_VARIANT` エラーになります。また `june.slide.tsx` と
 > `june.tsx`、`sales.csv` と `sales.tsx` はいずれも同じ URL に解決するので `ROUTE_CONFLICT` です。
 
+### ドキュメント（`.doc.tsx`）
+
+`.doc` も**ページ種別サフィックス**です（`src/june-summary.doc.tsx` → `/june-summary`）。上から下へ
+読む文章のページで、中身は `<Document>` を返す普通の React コンポーネントです。
+
+```tsx
+import { definePage } from "@squadbase/vantage";
+import { Document } from "@squadbase/vantage/doc";
+
+export const page = definePage({ title: "6月度サマリー" });
+
+export default function JuneSummary() {
+  return (
+    <Document>
+      <h1>6月度サマリー</h1>
+      <p>6月の売上は目標を 5% 上回りました。</p>
+      <table>…</table>
+    </Document>
+  );
+}
+```
+
+`<Document>` の中の見出し・段落・リスト・表・引用・コードには、クラスを書かなくてもスタイルが
+当たります。詳しくは [UI とテーマ](ui-and-theming)。`.slide` と同じく、`.doc` を付けられるのは
+ルートになるページモジュールだけです。
+
 ## ルーティングされないディレクトリ
 
 次のディレクトリは（どの階層でも）決して走査されません。ここには自由にコードを置けます。
@@ -214,7 +241,7 @@ export default function RootLayout() {
 | `label` | `string` | `navLabel` → `title` → `path` の順で決まる表示名 |
 | `title` / `description` / `navLabel` | `string \| undefined` | [`definePage`](pages-and-metadata) の値 |
 | `kind` | `"module" \| "file"` | 何から描かれるか。`"file"` は `.csv` / `.xlsx` |
-| `variant` | `"slide" \| undefined` | ページ種別サフィックス |
+| `variant` | `"slide" \| "doc" \| undefined` | ページ種別サフィックス |
 
 `useCurrentRoute()` は今表示中のルートを返します（404 のときは `undefined`）。
 上の例のような「現在地」判定のほか、パンくずやページ見出しに使えます。

package/docs/ja/ui-and-theming.md

@@ -114,6 +114,32 @@ pptx 書き出しが壊れる条件 — は同梱の **`vantage-slide` スキル
 > Tailwind でダッシュボード向けに組まれているので、1920×1080 を縮小投影すると `text-sm` のボタンは
 > 実効 8px 程度になって読めません。
 
+## ドキュメント（`/doc`）
+
+`<name>.doc.tsx` を[置くとドキュメントのページになります](routing)。`Document` で包むと、中に
+書いた素の HTML 要素（`h1`〜`h4`・`p`・`ul`/`ol`・`table`・`blockquote`・`pre`/`code`・`hr`・`a`・
+`figure`/`figcaption`・`img`）に見出しの大きさ・余白・罫線が当たります。チャートは
+[`EChart`](parts/echart) をそのまま文中に置けます。
+
+```tsx
+import { Document } from "@squadbase/vantage/doc";
+```
+
+配色・書体・本文の幅は `--doc-*` トークンで、既定はアプリのトークンへの別名なので
+**ダークモードにも自動で追従します**。
+
+| トークン | 既定 | 何に効くか |
+|---|---|---|
+| `--doc-fg` / `--doc-muted` | `--foreground` / `--muted-foreground` | 本文 / 引用・キャプション |
+| `--doc-accent` | `--primary` | リンク |
+| `--doc-border` / `--doc-subtle` | `--border` / `--muted` | 罫線 / コード・表の見出し行の背景 |
+| `--doc-font-body` / `--doc-font-heading` / `--doc-font-mono` | アプリの書体 | 本文 / 見出し / コード |
+| `--doc-size-body` / `--doc-line-height` / `--doc-max-width` | `1rem` / `1.8` / `48rem` | 文字サイズ / 行間 / 本文の幅 |
+
+アプリ全体では `styles.css` の `:root` で、1 つのドキュメントだけなら
+`<Document theme={{ accent: "#2563eb" }}>` で上書きします。要素に `className` で Tailwind
+ユーティリティを付けると、既定のスタイルより優先されます。
+
 ## Tailwind はそのまま使える
 
 `className` に Tailwind ユーティリティを書くだけで効きます。`tailwind.config` も `postcss.config`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squadbase/vantage",
-  "version": "0.6.0-dev.3cc6138",
+  "version": "0.6.1-dev.2d25e94",
   "description": "Data dashboard framework for Squadbase Editor. Vite-powered, config-free, one-file first.",
   "type": "module",
   "license": "MIT",
@@ -67,6 +67,10 @@
       "types": "./dist/slide/index.d.ts",
       "default": "./dist/slide/index.js"
     },
+    "./doc": {
+      "types": "./dist/doc/index.d.ts",
+      "default": "./dist/doc/index.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "default": "./dist/server/index.js"

package/skills/vantage-design/SKILL.md

@@ -0,0 +1,137 @@
+---
+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" で起動。
+---
+
+# DESIGN.md と styles.css をまとめて更新する
+
+Vantage アプリの見た目は 2 つのファイルで決まる。
+
+| ファイル | 持つもの | 所有者 |
+| --- | --- | --- |
+| `DESIGN.md`(プロジェクトルート) | 意図とルール。**トークン名だけ**を書き、色コードは書かない(150 行以内) | ユーザー |
+| `styles.css`(ページと同じ側。通常 `src/styles.css`) | トークンの実際の値(`:root` と `.dark`) | ユーザー |
+
+**2 つは必ず同じステップで更新する。** 片方だけ直すと、次にページを書くエージェントが古い意図に
+従ってしまう。デザイン変更の依頼をページ単位の `className` 修正で済ませない。
+
+一般規約(トークンで色を書く・設定ファイルを作らない)は `AGENTS.md` が正本。ここでは手順だけを扱う。
+
+## リファレンス
+
+| ファイル | 読む場面 |
+| --- | --- |
+| `references/format.md` | `DESIGN.md` を書く / 直すとき(書式・節の順番・雛形) |
+| `references/extract.md` | URL・画像・pptx/pdf・言葉・外部 DESIGN.md から色と書体を取り出すとき |
+| `references/presets.md` | プロジェクト作成時の初期デザイン(`default` / `calm` / `vivid` / `mono`) |
+| `scripts/contrast.mjs` | 文字色と背景色のコントラスト比を確かめるとき |
+
+## 手順
+
+### 1. 入力を集める
+
+- 何に合わせるのか(URL・ロゴ画像・資料・言葉・外部の `DESIGN.md`)を確認し、
+  `references/extract.md` の該当する節の手順で色・書体・トーンを取り出す。
+- 既存の `DESIGN.md` と `styles.css` を読む。既にあるルールで今回触らないものは残す。
+- スライド(`*.slide.tsx`)があるかを `ls` / `vantage routes` で確認しておく。
+
+### 2. 提案して確認を取る
+
+書き込む前に、次の 2 つをユーザーに見せて確認を取る。
+
+- **役割 → トークンの対応表**(主色・強調・良い/悪い/注意・背景の段階・文字・チャート 5 色・書体)。
+  各行に「何に合わせてその色にしたか」を 1 語添える。
+- **トーンの説明**(2〜3 行。`DESIGN.md` の「全体のトーン」にそのまま入る文)。
+
+プリセットで足りる場合はプリセット名(`references/presets.md`)で提案してよい。
+
+### 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` にしたいなど)は、マーカーブロックの**後ろ**に
+  別の `: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` の
+  `--slide-font-display`(見出し)/ `--slide-font-body`(本文)で決まる。Web フォントを使うときの
+  レシピ:
+  1. Google Fonts の CSS
+     (`curl -A '<ブラウザの User-Agent>' 'https://fonts.googleapis.com/css2?family=<Font>:wght@400;600&display=swap'`)
+     から使う subset の `@font-face` ブロックだけを `styles.css` の先頭に貼る。
+     **`@import url(...)` は使わない** ― `styles.css` はテーマの後ろに連結されるので
+     「@import rules must precede all rules」の警告とともにビルドで捨てられる。
+  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;
+       --slide-font-body: var(--slide-font-display);
+     }
+     ```
+
+  日本語の Web フォントは face が 100 を超えるので原則使わない(pptx 書き出しも壊れる。
+  `vantage-slide` の `references/tokens.md` 参照)。
+
+`DESIGN.md`: `references/format.md` の書式で書く。**色コードを書かない**(トークン名だけ)。
+150 行を超えない(超えると `vantage check` が `DESIGN_MD_TOO_LONG` を出す)。ロゴなどの素材は
+`public/brand/logo.svg` のように `public/` 配下のパスで「ブランド素材」行に書く。
+
+### 4. コントラストを確かめる
+
+主な文字色 / 背景色の組を、**ライトとダークの両方で**確かめる。
+
+```bash
+node <このスキルの場所>/scripts/contrast.mjs '<文字色>' '<背景色>'
+# 例: node .squadbase/skills/vantage-design/scripts/contrast.mjs 'oklch(0.985 0 0)' 'oklch(0.55 0.2 260)'
+```
+
+最低限の組: `--foreground` / `--background`、`--primary-foreground` / `--primary`、
+`--muted-foreground` / `--card`、`--destructive` / `--background`。本文は AA(4.5:1)、大きな数字・
+見出しだけに使う色は 3:1 以上。`var(--color-*)` で書いた値は Tailwind の `oklch()` 値に直してから渡す。
+落ちたら明度を調整して、提案に戻らずに直してよい(直したことは報告する)。
+
+### 5. プレビューを見せる(省略しない)
+
+- **必ず**使い捨てページ `src/design-preview.tsx`(`src/` が無ければルート直下)を作る: KPI カード
+  3〜4 枚、`EChart` の棒または折れ線 1 つ(5 系列)、主要ボタン・破壊的ボタン、補足の文字。すべて
+  トークンで書く。既存ページやホームで代用しない ― ホームなどの画面はチャートやボタンを持たないことが
+  多く、変更後の色が見えない。
+- スライドがあるなら既存のデッキの URL を案内する(プレビュー用のデッキは作らない)。
+- **ユーザーが承認したら `src/design-preview.tsx` を削除する。** 残すとナビに出る。
+
+### 6. 検証する
+
+```bash
+npx vantage check
+```
+
+`HARDCODED_COLOR`(ページ内の色コード)や `DESIGN_MD_TOO_LONG` が出たらその場で直す。
+
+### 7. 完了を報告する
+
+報告には、更新したファイル(`DESIGN.md` / `styles.css`)に加えて次を**必ず**入れる。
+
+- プレビューページのパスと URL(`src/design-preview.tsx` → `/design-preview`)。
+- 「ホームなど既存の画面は一部の色しか使っていないので、変更が見えないことがある。配色はプレビュー
+  ページで確認してほしい」という一言。
+
+## 会話中の指示との関係
+
+- 会話中の個別の指示(「このグラフだけ赤で」)は `DESIGN.md` より優先する。そのページだけ直せばよい。
+- 同じ指示が 2 回以上出たら、`DESIGN.md` への反映を提案する(反映するときはこの手順の 2 から)。