@squadbase/vantage-template 0.1.0-dev.a6b88b8 → 0.1.0-dev1.f48cfad

package/base-template/.squadbase/skills/vantage-design/scripts/contrast.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// WCAG 2.x contrast ratio between two CSS colours. No dependencies.
+//
+//   node contrast.mjs <foreground> <background>
+//   node contrast.mjs '#ffffff' 'oklch(0.205 0 0)'
+//   node contrast.mjs 'oklch(0.985 0 0)' 'var(--color-sky-700)'
+//
+// Accepts: #rgb / #rgba / #rrggbb / #rrggbbaa, rgb()/rgba(), oklch(), and
+// Tailwind palette references `var(--color-<name>-<step>)` (resolved from
+// node_modules/tailwindcss/theme.css, searched upward from the cwd).
+// A translucent foreground is composited over the background first; the
+// background is treated as opaque.
+
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+function usage(message) {
+  if (message) console.error(`error: ${message}`)
+  console.error("usage: node contrast.mjs <foreground> <background>")
+  console.error("       colours: #hex, rgb(), oklch(), var(--color-<name>-<step>)")
+  process.exit(2)
+}
+
+// --- parsing ---------------------------------------------------------------
+
+function parseNumber(token, percentScale = 1) {
+  const t = token.trim()
+  if (t === "none") return 0
+  if (t.endsWith("%")) return (Number.parseFloat(t) / 100) * percentScale
+  const n = Number.parseFloat(t)
+  if (Number.isNaN(n)) throw new Error(`not a number: ${token}`)
+  return n
+}
+
+function splitArgs(body) {
+  const [main, alpha] = body.split("/")
+  const parts = main.trim().split(/[\s,]+/).filter(Boolean)
+  return { parts, alpha: alpha === undefined ? 1 : parseNumber(alpha, 1) }
+}
+
+function srgbToLinear(c) {
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+}
+
+function linearToSrgb(c) {
+  const v = Math.min(1, Math.max(0, c))
+  return v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055
+}
+
+// Returns gamma-encoded sRGB channels in [0, 1] plus alpha.
+function parseHex(input) {
+  let hex = input.slice(1)
+  if (![3, 4, 6, 8].includes(hex.length) || /[^0-9a-f]/i.test(hex)) {
+    throw new Error(`bad hex colour: ${input}`)
+  }
+  if (hex.length <= 4) hex = [...hex].map((c) => c + c).join("")
+  const n = (i) => Number.parseInt(hex.slice(i, i + 2), 16) / 255
+  return { r: n(0), g: n(2), b: n(4), a: hex.length === 8 ? n(6) : 1 }
+}
+
+function parseRgb(body) {
+  const { parts, alpha } = splitArgs(body)
+  if (parts.length === 4) return parseRgb(`${parts.slice(0, 3).join(" ")} / ${parts[3]}`)
+  if (parts.length !== 3) throw new Error(`bad rgb(): ${body}`)
+  const [r, g, b] = parts.map((p) => parseNumber(p, 255) / 255)
+  return { r, g, b, a: alpha }
+}
+
+function parseOklch(body) {
+  const { parts, alpha } = splitArgs(body)
+  if (parts.length !== 3) throw new Error(`bad oklch(): ${body}`)
+  const L = parseNumber(parts[0], 1)
+  const C = parseNumber(parts[1], 0.4)
+  const H = (Number.parseFloat(parts[2]) || 0) * (Math.PI / 180)
+  const a = C * Math.cos(H)
+  const bb = C * Math.sin(H)
+  const l_ = (L + 0.3963377774 * a + 0.2158037573 * bb) ** 3
+  const m_ = (L - 0.1055613458 * a - 0.0638541728 * bb) ** 3
+  const s_ = (L - 0.0894841775 * a - 1.291485548 * bb) ** 3
+  const r = 4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_
+  const g = -1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_
+  const b = -0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_
+  return { r: linearToSrgb(r), g: linearToSrgb(g), b: linearToSrgb(b), a: alpha }
+}
+
+let tailwindTheme
+function findTailwindTheme() {
+  if (tailwindTheme !== undefined) return tailwindTheme
+  tailwindTheme = null
+  let dir = process.cwd()
+  for (;;) {
+    for (const rel of [
+      "node_modules/tailwindcss/theme.css",
+      "node_modules/@squadbase/vantage/node_modules/tailwindcss/theme.css",
+    ]) {
+      const file = join(dir, rel)
+      if (existsSync(file)) {
+        tailwindTheme = readFileSync(file, "utf8")
+        return tailwindTheme
+      }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return tailwindTheme
+    dir = parent
+  }
+}
+
+function resolveVar(input) {
+  const name = input.match(/^var\(\s*(--color-[a-z]+-\d+)\s*\)$/)?.[1]
+  if (!name) throw new Error(`only var(--color-<name>-<step>) can be resolved: ${input}`)
+  const theme = findTailwindTheme()
+  if (!theme) throw new Error(`tailwindcss/theme.css not found from ${process.cwd()}; pass the value instead`)
+  const value = theme.match(new RegExp(`${name}:\\s*([^;]+);`))?.[1]
+  if (!value) throw new Error(`${name} is not in tailwindcss/theme.css`)
+  return value.trim()
+}
+
+function parseColor(raw) {
+  const input = raw.trim().toLowerCase()
+  if (input.startsWith("#")) return parseHex(input)
+  if (input.startsWith("var(")) return parseColor(resolveVar(input))
+  const fn = input.match(/^([a-z]+)\((.*)\)$/)
+  if (fn) {
+    if (fn[1] === "rgb" || fn[1] === "rgba") return parseRgb(fn[2])
+    if (fn[1] === "oklch") return parseOklch(fn[2])
+  }
+  throw new Error(`unsupported colour: ${raw}`)
+}
+
+// --- contrast --------------------------------------------------------------
+
+function composite(fg, bg) {
+  const mix = (f, b) => f * fg.a + b * (1 - fg.a)
+  return { r: mix(fg.r, bg.r), g: mix(fg.g, bg.g), b: mix(fg.b, bg.b), a: 1 }
+}
+
+function luminance({ r, g, b }) {
+  return 0.2126 * srgbToLinear(r) + 0.7152 * srgbToLinear(g) + 0.0722 * srgbToLinear(b)
+}
+
+function toHex({ r, g, b }) {
+  const h = (c) => Math.round(Math.min(1, Math.max(0, c)) * 255).toString(16).padStart(2, "0")
+  return `#${h(r)}${h(g)}${h(b)}`
+}
+
+const [fgArg, bgArg] = process.argv.slice(2)
+if (!fgArg || !bgArg) usage()
+
+let fg
+let bg
+try {
+  bg = { ...parseColor(bgArg), a: 1 }
+  fg = composite(parseColor(fgArg), bg)
+} catch (error) {
+  usage(error.message)
+}
+
+const [hi, lo] = [luminance(fg), luminance(bg)].sort((x, y) => y - x)
+const ratio = (hi + 0.05) / (lo + 0.05)
+const verdict = (min) => (ratio >= min ? "PASS" : "FAIL")
+
+console.log(`foreground ${fgArg} (${toHex(fg)})`)
+console.log(`background ${bgArg} (${toHex(bg)})`)
+console.log(`contrast   ${ratio.toFixed(2)}:1`)
+console.log(`AA normal text (>= 4.5:1): ${verdict(4.5)}`)
+console.log(`AA large text / UI (>= 3:1): ${verdict(3)}`)

package/base-template/AGENTS.md

@@ -7,6 +7,8 @@
 > このファイルと `agents/*.md` は、いずれも **Vantage フレームワークが所有する正本**の
 > コピーです。手で書き換えても、`vantage upgrade` を実行するとフレームワーク同梱の正本から
 > 再同期されて上書きされます。アプリ固有のメモは別ファイル(例: `README.md`)に書いてください。
+> 例外はプロジェクトルートの `DESIGN.md` で、これは**ユーザーが所有**します(`vantage upgrade` も
+> `vantage add agents` も触らない。→「デザインの意図(DESIGN.md)」)。
 >
 > 手順を伴う踏み込んだワークフローは、同梱の Claude Code Skill に分かれています。このファイルは
 > 「地図」、`agents/*.md` は「種類ごとの静的リファレンス」、Skill は「手順書」という役割分担です。
@@ -94,6 +96,7 @@ root/
 | `@squadbase/vantage/components` | 複合パーツ(`PageShell`・`DashboardCardPreset`・`DataTablePreset`・`EChart` ほか) |
 | `@squadbase/vantage/table` | `FilePageView`・`TableViewer`(データファイルページの表ビューア) |
 | `@squadbase/vantage/slide` | `SlideDeck`・`Slide`・`Steps`・`Step`・`MorphElement`・`useSlideNumber`・`useIsActiveSlide`(スライド専用。1920×1080 の固定キャンバス) |
+| `@squadbase/vantage/doc` | `Document`(ドキュメント専用。中の素の HTML 要素に見出し・表などのスタイルが当たる) |
 | `@squadbase/vantage/markdown` | `MarkdownRenderer`(Shiki を隔離するための専用サブパス) |
 | `@squadbase/vantage/server` | `ApiContext`・`ApiHandler`・`HttpError`・`isHttpError`・`json`(server/ 側でのみ使う) |
 
@@ -108,6 +111,18 @@ root/
 - `server/` が**無い** → 外部 API を直接叩くなら `useQuery`(→ `agents/page.md`)。自前の API が
   要るようになったら `server/api/*.ts` を足すだけでよい(設定変更は不要)。
 
+## デザインの意図(DESIGN.md)
+
+プロジェクトルートに `DESIGN.md` があれば、**UI(ページ・スライド・コンポーネント)を書く前に
+読む。** 色・チャート・書体・レイアウトの使い分けがトークン名で書いてあるので、それに従って
+トークンで書く(値は `styles.css` にあり、`DESIGN.md` には色コードを書かない)。
+
+- **会話中の指示は `DESIGN.md` より優先する。** 同じ指示が繰り返されたら、`DESIGN.md` への
+  反映をユーザーに提案する。
+- **「色を変えて」「ブランドに合わせて」などデザイン全体の変更は、ファイルごとに直さない。**
+  Skill `vantage-design` の手順で `DESIGN.md` と `styles.css` をまとめて更新する。
+- `DESIGN.md` はユーザーの持ち物。`vantage upgrade` は書き換えない。
+
 ## 何を書くか → どのファイルを読むか
 
 **書こうとしている種類のファイルだけを開けばよい。** まず該当する 1 ファイルを readFiles で
@@ -118,6 +133,7 @@ root/
 | ダッシュボード / 通常ページ(`.tsx`) | `agents/page.md` |
 | API(`server/`) | `agents/api.md` |
 | スライド(`.slide.tsx`) | `agents/slide.md` |
+| ドキュメント(`.doc.tsx`) | `agents/doc.md` |
 | `.xlsx` ページ | `agents/xlsx.md` |
 | `.csv` ページ | `agents/csv.md` |
 
@@ -173,6 +189,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-pitfalls`** — Base UI(≠ Radix)の癖など、静かに壊れる落とし穴のリファレンス
 - **`project-storage`** — Squadbase の Project Storage(アップロード済みファイル)をブラウザから読み書きする
 
@@ -314,3 +331,21 @@ const res = await fetch(`${baseUrl}/queries/${QUERY_ID}?since=2026-01-01`, {
 - **データ取得の失敗は各ページが `ErrorState` で出す。** `BuildRecovery` が拾うのは
   「レンダリングが throw した」場合だけで、`useApiQuery` の `isError` はページの責任
   (→ `agents/page.md` の「データ取得」)。
+
+## 依存の追加とスクリプトの実行は bun で
+
+このプロジェクトの package manager は **bun** です(`squadbase.yml` の `package_manager: bun`、
+lockfile は `bun.lock`)。Squadbase のサンドボックスは bun と依存のキャッシュを持っており、
+`bun install` はキャッシュだけで終わります。上のフレームワーク規約に出てくる
+`pnpm install` / `pnpm dev` / `pnpm check` は、そのまま `bun install` / `bun run dev` /
+`bun run check` に読み替えてください。
+
+### 追加の不変条件
+
+- **依存を足すときは `bun add <pkg>`(開発用は `bun add -d <pkg>`)。** `npm install` や
+  `pnpm add` を使わない — `package-lock.json` / `pnpm-lock.yaml` が生えて `bun.lock` と別の断面に
+  なり、次回起動時の install が lockfile を作り直す。
+- **`bun.lock` を消さない・手で編集しない。** `package.json` の依存を直接書き換えたときは
+  `bun install` を一度走らせて `bun.lock` を追従させ、両方を同じコミットに入れる。
+- スクリプトは `bun run <script>`(`bun run dev` / `bun run build` / `bun run check` /
+  `bun run routes`)。`npm run <script>` でも動くが、install に npm を使わないこと。

package/base-template/DESIGN.md

@@ -0,0 +1,108 @@
+<!--
+DESIGN.md — このアプリの「見た目の意図」を書くファイルです。
+
+- 実際の色・角丸・書体の値は src/styles.css にあります。ここにはトークン名(--primary など)と
+  使い分けのルールだけを書き、色コードは書きません。
+- エージェントはページ・スライド・コンポーネントを書く前にこのファイルを読みます。
+  会話の中での指示はこのファイルより優先されます。
+- 「このサイトに合わせて」「色を落ち着いた感じに」と頼めば、このファイルと styles.css を
+  まとめて更新します。
+- このファイルはあなたのものです。`vantage upgrade` が書き換えることはありません。
+-->
+
+# デザイン
+
+## 全体のトーン (Overview)
+
+- 落ち着いた無彩色のベースに、データだけが色を持つ業務ダッシュボード。
+- 装飾より読みやすさを優先する。影・グラデーション・アニメーションは最小限。
+- 数字が主役。1 画面で伝えたいことを 1 つに絞り、補足は小さく添える。
+- ブランド素材: なし(ロゴを使う場合は `public/brand/logo.svg` のように `public/` 配下のパスで書く)
+
+## 色 (Colors)
+
+色は必ずトークン(Tailwind のセマンティッククラス)で指定する。素のパレット(`bg-blue-600` など)や
+色コードを直接書かない。
+
+| 役割 | トークン | 使う場所 |
+| --- | --- | --- |
+| 主色 (Primary) | `--primary` / `--primary-foreground` | 主要ボタン、選択中の状態。既定は無彩色 |
+| 強調 (Accent) | `--chart-1` | 1 つだけ目立たせたい数値・系列・リンク的な強調 |
+| 良い (Positive) | `--chart-2` | 前期比のプラスなど、良い変化の小さな印 |
+| 悪い (Negative) | `--destructive` | 前期比のマイナス、エラー、削除操作 |
+| 注意 (Warning) | 専用トークンなし | 文言とアイコンで示し、色は `--muted-foreground` |
+| 背景の段階 | `--background` → `--card` → `--muted` | ページ → カード → カード内の区画・ホバー |
+| 境界 | `--border` / `--input` / `--ring` | 罫線、入力欄、フォーカス |
+| 文字 | `--foreground` / `--muted-foreground` | 本文 / 補足・ラベル・単位 |
+
+- `--muted`・`--accent`・`--secondary`・`--border` は背景・境界用。文字色に使わない。
+- 増減(▲▼・前期比)は向きで色を分ける: 増加・プラスは `--chart-2`(または `--primary`)、
+  減少・マイナスは `--destructive`。下向きの矢印やマイナスを `--primary` で塗らない。
+- ライトとダークの両方がトークンで決まるので `dark:` を並べない。
+
+## チャート (Charts)
+
+- 系列の順番は `--chart-1` → `--chart-2` → `--chart-3` → `--chart-4` → `--chart-5`
+  (現在はプリセット `blue`: 青 → ティール → フクシア → バイオレット → グレー)。
+- 1 系列だけを目立たせるときは、その系列を `--chart-1`、残りをすべて `--chart-5`(グレー)にする。
+- 良い / 悪いを色で塗り分けるときは `--chart-2` / `--destructive`。色だけに頼らず ▲▼ や符号も添える。
+- 系列は 5 つまで。それ以上はグループ化するか「その他」にまとめる。
+- 禁止: 同じチャートで `--destructive` を普通の系列色として使う(悪い値に見える)。
+- 禁止: 隣り合う系列に `--chart-3` と `--chart-4` を並べて細い線で描く(見分けにくい)。
+- 配色を丸ごと変えるときは `npx @squadbase/vantage-template chart <preset>` を使う
+  (`blue` / `ocean` / `sunset` / `forest` / `berry` / `mono`)。
+
+## 書体 (Typography)
+
+| 用途 | 指定 | 備考 |
+| --- | --- | --- |
+| 見出し・本文 | システムフォント(`body` の `font-family`) | Web フォントは使わない |
+| 数字 | 同上 + `tabular-nums` | 桁がそろうように必ず付ける |
+| スライドの見出し | `--slide-font-display` | 既定は日本語を含むシステムフォント |
+| スライドの本文 | `--slide-font-body` | 既定は見出しと同じ |
+
+サイズの段階(ダッシュボード):
+
+- ページ見出し: `text-2xl font-bold`
+- カード見出し・ラベル: `text-sm font-medium text-muted-foreground`
+- KPI の数値: `text-3xl font-semibold tabular-nums`
+- 本文・表: `text-sm`
+- 注釈・出典: `text-xs text-muted-foreground`
+
+スライドのサイズは `--slide-size-hero`(表紙・大きな数字)と `--slide-size-body`(本文)を基準にする。
+
+## レイアウトと密度 (Layout)
+
+- 情報はカード(`bg-card` + `border-border`)で区切る。角丸は `--radius` に従う(個別に変えない)。
+- グリッドの間隔は `gap-4`。セクション間は `gap-6` 程度。
+- KPI は 1 行に 2〜4 枚。その下にチャート、最後に明細の表。
+- 密度は「中」。余白を削って詰め込むより、ページを分ける。
+
+## 成果物の種類ごとの規則 (Per-artifact)
+
+### ダッシュボード
+
+- 先頭に KPI カード、次にトレンドのチャート、最後に明細の表。
+- 各 KPI には比較対象(前月比・目標比など)を 1 つ添える。
+- チャートのタイトルは結論を書く(「売上推移」より「売上は 3 か月連続で増加」)。
+
+### スライド
+
+- 1 枚に 1 メッセージ。見出しに結論を書く。
+- 色は `--slide-bg` / `--slide-fg` / `--slide-accent` / `--slide-muted` を使う
+  (既定では `--background` / `--foreground` / `--primary` / `--muted-foreground` に連動)。
+- 強調色は 1 枚につき 1 か所まで。
+
+## Do / Don't
+
+Do:
+
+- トークンと Tailwind のセマンティッククラスで色を指定する。
+- 数値には単位と比較対象を付ける。
+- 色の意味(良い / 悪い / 強調)をアプリ全体でそろえる。
+
+Don't:
+
+- 色コードや素のパレットクラスを直接書く。
+- 1 画面で強調色を何か所にも使う。
+- 3D チャート・円グラフの多用・装飾目的のグラデーション。

package/base-template/agents/doc.md

@@ -0,0 +1,73 @@
+# ドキュメント(.doc.tsx)
+
+フレームワーク所有の知識ファイルで、`vantage upgrade` で再同期されます。`.doc.tsx` で
+ドキュメントを書くときに読んでください。不変条件・ディレクトリ構造は `AGENTS.md` を
+先に読んでいる想定です。
+
+## ドキュメントは `.doc.tsx` で書く
+
+`src/june-summary.doc.tsx` → `/june-summary`。上から下へ読む文章のページで、表やチャートを
+文中に置けます。中身は `<Document>` を返す普通の React コンポーネントで、`definePage` もナビも
+通常のページと同じように効きます。
+
+```tsx
+import { definePage } from "@squadbase/vantage"
+import { EChart } from "@squadbase/vantage/components"
+import { Document } from "@squadbase/vantage/doc"
+
+export const page = definePage({ title: "6月度サマリー", navLabel: "6月度サマリー" })
+export default function JuneSummary() {
+  return (
+    <Document>
+      <h1>6月度サマリー</h1>
+      <p>6月の売上は <strong>5,250 万円</strong>で、目標を 5% 上回りました。</p>
+      <h2>週次の売上</h2>
+      <figure>
+        <EChart option={option} height={280} ariaLabel="6月の週次売上" />
+        <figcaption>第4週はキャンペーン初週</figcaption>
+      </figure>
+      <table>…</table>
+    </Document>
+  )
+}
+```
+
+## 書き方
+
+- **素の HTML 要素で書く。** `<Document>` の中の `h1`〜`h4`・`p`・`ul`/`ol`/`li`・`table`・
+  `blockquote`・`pre`/`code`・`hr`・`a`・`figure`/`figcaption`・`img` には、見出しの大きさ・余白・
+  罫線などが最初から当たっています。クラスは要りません。
+- **Tailwind のユーティリティは、その要素だけ見た目を変えたいときに使う。** 要素の既定の
+  スタイルはユーティリティより弱いので、`className` を付ければそちらが勝ちます。ドキュメント全体の
+  見た目を変えたいときはユーティリティを並べず、下の `--doc-*` を変えます。
+- **数値はコードに直接書く。** ドキュメントは書いた時点の内容を残すページです。
+  `useApiQuery` などで読み込むと、開くたびに値が変わります。
+- **チャートは `EChart`(`@squadbase/vantage/components`)を文中に置く。** `figure` で囲めば
+  `figcaption` がキャプションになります。
+- **ページ全体を包むのは `<Document>` だけ。** `PageShell` などのダッシュボード用の枠で包まない
+  (本文の幅と余白は `<Document>` が決めます)。
+
+## 見た目を変える
+
+配色・書体・本文の幅は `--doc-*` の CSS 変数です。既定値はアプリのトークンへの別名なので、
+ダークモードにもそのまま追従します。
+
+| 変数 | 既定値 | 何に効くか |
+| --- | --- | --- |
+| `--doc-fg` | `var(--foreground)` | 本文の文字色 |
+| `--doc-muted` | `var(--muted-foreground)` | 引用・キャプション |
+| `--doc-accent` | `var(--primary)` | リンク |
+| `--doc-border` | `var(--border)` | 表・`h2` の下線・引用・`hr` |
+| `--doc-subtle` | `var(--muted)` | コード・表の見出し行の背景 |
+| `--doc-font-body` / `--doc-font-heading` / `--doc-font-mono` | アプリの書体 | 本文 / 見出し / コード |
+| `--doc-size-body` | `1rem` | 本文の文字サイズ(見出しはこれに比例) |
+| `--doc-line-height` | `1.8` | 本文の行間 |
+| `--doc-max-width` | `48rem` | 本文の幅 |
+
+アプリのすべてのドキュメントに効かせるなら `styles.css` の `:root` で定義し直します。1 つの
+ドキュメントだけなら `<Document theme={{ accent: "#2563eb", maxWidth: "56rem" }}>` のように
+`theme` で渡します(`theme` のキーは変数名から `--doc-` を外してキャメルケースにしたもの)。
+
+`.doc` を付けられるのはルートになるページモジュールだけで、`_layout.doc.tsx` などは
+`INVALID_PAGE_VARIANT` エラーになります。`june.doc.tsx` と `june.tsx` は同じ URL に解決するので
+`ROUTE_CONFLICT` です。

package/base-template/agents/page.md

@@ -4,6 +4,8 @@
 (ダッシュボード)を書くときに読んでください。前提となる不変条件・ディレクトリ構造は
 `AGENTS.md` を先に読んでいる想定です。
 
+プロジェクトルートに `DESIGN.md` があれば、書き始める前に読んで配色・書体・レイアウトの規則に従う。
+
 ## 最小アプリ(2 ファイル)
 
 `package.json` と `index.tsx` の 2 ファイルだけで動く。

package/base-template/agents/slide.md

@@ -4,6 +4,8 @@
 スライドデッキを書くときに読んでください。不変条件・ディレクトリ構造は `AGENTS.md` を
 先に読んでいる想定です。
 
+プロジェクトルートに `DESIGN.md` があれば、書き始める前に読んで「スライド」の節と配色・書体の規則に従う。
+
 ## スライドは `.slide.tsx` で書く
 
 `src/monthly-report.slide.tsx` → `/monthly-report`。中身は `<SlideDeck>` を返す普通の React
@@ -23,6 +25,11 @@ 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>`)。
+
 1920×1080 の固定キャンバスに絶対 px で書き、画面サイズに合わせて縮小されます。キー / クリックで
 送れ、左のスライド一覧(サムネイル列)は `L` で開閉、`F` で全画面、ツールバーから pptx を
 書き出せます。**書き方の作法は同梱 Skill の