@squadbase/vantage 0.6.2-dev1.05a930b → 0.6.2-dev1.100dfeb

package/registry/ui/echart.tsx

@@ -691,6 +691,116 @@ export function echartSetOptionOpts(prev: EChartsOption | null, next: EChartsOpt
   return { notMerge: false, replaceMerge: [...types], lazyUpdate: true }
 }
 
+/**
+ * Component types that get a generated `id` when the option has none, so replaceMerge can match them across updates.
+ * Not `dataset` / `graphic` / `tooltip`: they are rebuilt on every update (there is nothing to transition).
+ */
+const ID_TYPES = [
+  "title", "legend", "grid", "xAxis", "yAxis", "polar", "radiusAxis", "angleAxis", "radar",
+  "dataZoom", "visualMap", "geo", "singleAxis", "calendar",
+] as const
+
+/**
+ * What `withStableIds` remembers between updates: per generated id, the shape last applied and how many
+ * times it changed (the id's `~v<n>` suffix); per component type, the order of its ids.
+ */
+export interface StableIdState {
+  ids: Map<string, { shape: string; version: number }>
+  order: Map<string, string[]>
+}
+export const createStableIdState = (): StableIdState => ({ ids: new Map(), order: new Map() })
+
+/**
+ * Shape of a component: which keys it has, recursively (arrays only as "array", values not at all —
+ * except `type`). A merge keeps keys the new option dropped, so a changed shape must not be merged.
+ */
+function shapeOf(v: unknown): string {
+  if (Array.isArray(v)) return "[]"
+  if (!v || typeof v !== "object" || Object.getPrototypeOf(v) !== Object.prototype) return "."
+  const o = v as Record<string, unknown>
+  return `{${Object.keys(o)
+    .filter((k) => o[k] !== undefined)
+    .sort()
+    .map((k) => (k === "type" || k === "id" ? `${k}=${String(o[k])}` : `${k}:${shapeOf(o[k])}`))
+    .join(",")}}`
+}
+
+/**
+ * Gives every series (and the common components) an `id` it does not have yet —
+ * series: `series:<name ?? index>`, others `<type>:<index>` — so an update that
+ * only changes values is matched to the existing component and transitions
+ * instead of being rebuilt. If the component's shape changed since `state` last
+ * saw it (a key was removed or added, the type changed), the id gets a new
+ * `~v<n>` suffix so replaceMerge builds it from scratch: the result then always
+ * equals applying the option with `notMerge`. Explicit ids are kept; the input is not mutated.
+ */
+export function withStableIds(option: EChartsOption, state: StableIdState = createStableIdState()): EChartsOption {
+  const out: Record<string, unknown> = { ...(option as Record<string, unknown>) }
+  const taken = new Set<string>()
+  const list = (v: unknown): Record<string, unknown>[] | null =>
+    Array.isArray(v) ? (v as Record<string, unknown>[]) : v && typeof v === "object" ? [v as Record<string, unknown>] : null
+  const give = (key: string, pick: (c: Record<string, unknown>, i: number) => string) => {
+    const items = list(out[key])
+    if (!items) return
+    const used = new Set<string>(items.flatMap((c) => (c && c.id != null ? [String(c.id)] : [])))
+    const bases = items.map((c, i) => {
+      if (!c || typeof c !== "object" || c.id != null) return null
+      let base = pick(c, i)
+      for (let n = 2; used.has(base) || taken.has(`${key}\u0000${base}`); n++) base = `${pick(c, i)}#${n}`
+      used.add(base)
+      taken.add(`${key}\u0000${base}`)
+      return base
+    })
+    // A merge fills the empty slots a removal left and keeps the slot order of what exists, so after any
+    // change in which components there are (or their order) it would not match a fresh render: rebuild them all.
+    const prevOrder = state.order.get(key) ?? []
+    const cur = bases.filter((b): b is string => b !== null)
+    const inOrder = cur.length === prevOrder.length && cur.every((b, i) => b === prevOrder[i])
+    state.order.set(key, cur)
+    out[key] = items.map((c, i) => {
+      const base = bases[i]
+      if (base == null) return c
+      const shape = shapeOf(c)
+      const prev = state.ids.get(base)
+      const version = !prev ? 0 : prev.shape === shape && inOrder ? prev.version : prev.version + 1
+      state.ids.set(base, { shape, version })
+      return { ...c, id: version ? `${base}~v${version}` : base }
+    })
+  }
+  give("series", (c, i) => `series:${typeof c.name === "string" && c.name ? c.name : i}`)
+  for (const key of ID_TYPES) give(key, (_c, i) => `${key}:${i}`)
+  return out as EChartsOption
+}
+
+/** Copy of the plain objects / arrays of an option (functions, class instances, Dates stay shared), to compare against later in-place edits. */
+export function snapshotOption<T>(v: T): T {
+  if (Array.isArray(v)) return v.map(snapshotOption) as T
+  if (v && typeof v === "object") {
+    const proto = Object.getPrototypeOf(v)
+    if (proto === Object.prototype || proto === null) {
+      return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, snapshotOption(x)])) as T
+    }
+  }
+  return v
+}
+
+/** Structural equality for option trees; functions and other non-plain objects compare by reference. */
+export function optionEquals(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (typeof a !== "object" || typeof b !== "object" || !a || !b) return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  if (Array.isArray(a)) {
+    const bb = b as unknown[]
+    return a.length === bb.length && a.every((v, i) => optionEquals(v, bb[i]))
+  }
+  if (a instanceof Date || b instanceof Date) return a instanceof Date && b instanceof Date && a.getTime() === b.getTime()
+  const pa = Object.getPrototypeOf(a)
+  if ((pa !== Object.prototype && pa !== null) || Object.getPrototypeOf(b) !== pa) return false
+  const ka = Object.keys(a)
+  const kb = Object.keys(b)
+  return ka.length === kb.length && ka.every((k) => Object.hasOwn(b, k) && optionEquals((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]))
+}
+
 /** `graphic` text doesn't inherit the global `textStyle`, so give it the inherited font unless it sets its own. */
 function withGraphicFont(option: EChartsOption, fontFamily: string | undefined): EChartsOption {
   const graphic = (option as { graphic?: unknown }).graphic
@@ -748,6 +858,9 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
   const reducedMotion = usePrefersReducedMotion()
   // What the current instance last received, to pick the merge mode of the next update.
   const appliedRef = useRef<EChartsOption | null>(null)
+  // The option (before ids) as it was when applied, deep-copied; and the shape history behind the generated ids.
+  const snapshotRef = useRef<EChartsOption | null>(null)
+  const idStateRef = useRef<StableIdState>(createStableIdState())
 
   const autoTheme = useMemo(() => (tokens ? buildChartTheme(tokens) : undefined), [tokens])
   const resolvedTheme = theme ?? autoTheme
@@ -759,6 +872,7 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
     if (!container) return
     const inst = init(container, resolvedTheme, { renderer: "canvas" })
     appliedRef.current = null
+    snapshotRef.current = null
     // `data-rendering` stays on until the (animated) paint is done, so anything
     // capturing the page — printing a document — can wait for real pixels.
     container.dataset.rendering = ""
@@ -786,10 +900,18 @@ export const EChart = forwardRef<HTMLDivElement, EChartProps>(function EChart(
 
   useEffect(() => {
     if (!instance || instance.isDisposed()) return
+    const prepared = withGraphicFont(
+      withMotionPreference(option, reducedMotion),
+      theme === undefined ? tokens?.fontFamily : undefined,
+    )
+    // Same content as last time (a re-render that built an equal option): nothing to redraw.
+    // Compared with a snapshot, so an in-place edit of a nested array of the caller's option still counts as a change.
+    if (snapshotRef.current && optionEquals(snapshotRef.current, prepared)) return
     if (containerRef.current) containerRef.current.dataset.rendering = ""
-    const next = withGraphicFont(withMotionPreference(option, reducedMotion), theme === undefined ? tokens?.fontFamily : undefined)
+    const next = withStableIds(prepared, idStateRef.current)
     instance.setOption(next, echartSetOptionOpts(appliedRef.current, next))
     appliedRef.current = next
+    snapshotRef.current = snapshotOption(prepared)
   }, [instance, option, reducedMotion, theme, tokens?.fontFamily])
 
   useEffect(() => {

package/registry/ui/kpi-card.tsx

@@ -43,7 +43,7 @@
  *   line takes its name from it ("昨日 617"), the same way a `label` on any `vs` does.
  * - **Two or more comparisons sit under the value**, not beside it, so the value
  *   keeps its place and its width whatever the card holds.
- * - **Polarity drives everything.** With `polarity="lower-is-better"` the target
+ * - **`betterWhen` drives everything.** With `betterWhen="down"` the target
  *   is met at or below it, and the record badge marks the lowest value.
  * - **Rates change in points.** With a `percent` format the delta and
  *   `{difference}` are in percentage points ("-0.5pt"); `change="relative"` opts
@@ -147,7 +147,9 @@ export interface KpiCardProps extends Omit<ComponentProps<"div">, "children"> {
    * @example provisional  /  provisional={{ label: "暫定" }}
    */
   provisional?: boolean | { label?: string }
-  /** Whether a rise is good. Default `"higher-is-better"`. `"neutral"` never colours the change and skips the target and record logic. */
+  /** Which direction is good: `"up"` (default) or `"down"` (churn, error rate). Wins over `polarity`. */
+  betterWhen?: "up" | "down"
+  /** @deprecated Older name of `betterWhen` (`"higher-is-better"` / `"lower-is-better"`). `"neutral"` (never colours the change, skips the target and record logic) is only reachable here. `betterWhen` wins if both are given. */
   polarity?: Polarity
   /** `"relative"` ("+12.4%"), `"points"` ("-0.5pt") or `"difference"` ("+¥530万", in `format`). Default: points for a `percent` format, else relative. */
   change?: ChangeDisplay
@@ -160,7 +162,7 @@ export interface KpiCardProps extends Omit<ComponentProps<"div">, "children"> {
   /**
    * Target for the current period. Under the value it adds a 6px bar (actual, the pace
    * projection, a tick at the target) and one line "目標の 49%・このペースなら 98%"
-   * (the projection only while `period` is in progress). With `polarity="lower-is-better"`
+   * (the projection only while `period` is in progress). With `betterWhen="down"`
    * or a rate target (points) there is no bar: "目標 … まであと …" in the footer.
    */
   target?: number
@@ -325,7 +327,8 @@ export function KpiCard({
   comparison: comparisonProp,
   comparisons,
   provisional,
-  polarity,
+  betterWhen,
+  polarity: polarityProp,
   change,
   neutralBand,
   showPrevious = true,
@@ -352,6 +355,8 @@ export function KpiCard({
   const isProvisional = provisional !== undefined && provisional !== false
   const provisionalLabel = typeof provisional === "object" && provisional.label ? provisional.label : "速報"
   const sample = useSampleMark()
+  // `betterWhen` is the documented name and wins over the older `polarity`.
+  const polarity: Polarity | undefined = betterWhen ? (betterWhen === "down" ? "lower-is-better" : "higher-is-better") : polarityProp
   const neutral = polarity === "neutral"
   const hasPrevious = comparison !== undefined && showPrevious
   // Two or more badges would squeeze the value from the right; they get their own row under it instead.

package/skills/vantage-design/SKILL.md

@@ -1,71 +1,76 @@
 ---
 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)アプリのテーマ(色・チャートの色・書体・角丸)を、`styles.css` とテーマコマンドで作る / 更新する手順。配色・ブランドカラー・テーマ・チャートの色・フォント・角丸・トーンを変えたいとき、既存サイトやロゴ・資料に合わせたいとき、プロジェクト作成時の初期デザイン(テーマ neutral / ocean / forest / sunset / violet / rose / mono)を決めるときに使う。「色を変えて」「ブランドに合わせて」「このサイトに合わせて」「落ち着いた感じに」「フォントを変えて」「テーマを作って」、"change the colors", "match our brand", "match this website", "theme", "color palette", "font", "design system" で起動。
 ---
 
-# DESIGN.md と styles.css をまとめて更新する
+# テーマと styles.css を更新する
 
-Vantage アプリの見た目は 2 つのファイルで決まる。
+Vantage アプリの色・書体・角丸の値と色の割り当ては、SquadKit のテーマだけが持つ。
 
-| ファイル | 持つもの | 所有者 |
-| --- | --- | --- |
-| `DESIGN.md`(プロジェクトルート) | 意図とルール。**トークン名だけ**を書き、色コードは書かない(150 行以内) | ユーザー |
-| `styles.css`(ページと同じ側。通常 `src/styles.css`) | トークンの実際の値(`:root` と `.dark`) | ユーザー |
+| 手段 | 何を決めるか |
+| --- | --- |
+| ThemeDialog / `theme <id>` / `chart <preset>`(CLI) | 出発点のテーマとチャートの配色 |
+| `styles.css`(ページと同じ側。通常 `src/styles.css`)の `/* squadkit-theme:end */` より後ろ | ブランド色・書体など、テーマに無い値の上書き |
 
-**2 つは必ず同じステップで更新する。** 片方だけ直すと、次にページを書くエージェントが古い意図に
-従ってしまう。デザイン変更の依頼をページ単位の `className` 修正で済ませない。
+デザイン変更の依頼(「もっと落ち着いた色に」など)は、**テーマの切り替えかスタイルシートの上書きで完結させる。**
+`DESIGN.md` へは記録しない。今のテーマ名は `styles.css` の `/* theme: <name> */` マーカーから読む。
+ページ単位の `className` 修正で済ませない。
 
-一般規約(トークンで色を書く・設定ファイルを作らない)は `AGENTS.md` が正本。ここでは手順だけを扱う。
+見た目の規則(意味トークンの使い分け・カードで包む・KPI → チャート → 表など)は `AGENTS.md` の
+「見た目の規約」節が正本。ここでは手順だけを扱い、規則は重複させない。
+任意の `DESIGN.md`(ユーザー固有の意図を書くファイル)は、ユーザーが望んだときだけ扱う(`references/format.md`)。
 
 ## リファレンス
 
 | ファイル | 読む場面 |
 | --- | --- |
-| `references/format.md` | `DESIGN.md` を書く / 直すとき(書式・節の順番・雛形) |
-| `references/extract.md` | URL・画像・pptx/pdf・言葉・外部 DESIGN.md から色と書体を取り出すとき |
-| `references/presets.md` | プロジェクト作成時の初期デザイン(`default` / `calm` / `vivid` / `mono`) |
+| `references/format.md` | ユーザーが任意の `DESIGN.md` を望んだとき(位置づけと優先順位) |
+| `references/extract.md` | URL・画像・pptx/pdf・言葉から色と書体を取り出すとき |
+| `references/presets.md` | テーマ(`neutral` / `ocean` / `forest` / `sunset` / `violet` / `rose` / `mono`)の選び方と `theme` コマンド。旧プリセット id の読み替え |
 | `scripts/contrast.mjs` | 文字色と背景色のコントラスト比を確かめるとき |
 
 ## 手順
 
 ### 1. 入力を集める
 
-- 何に合わせるのか(URL・ロゴ画像・資料・言葉・外部の `DESIGN.md`)を確認し、
+- 何に合わせるのか(URL・ロゴ画像・資料・言葉)を確認し、
   `references/extract.md` の該当する節の手順で色・書体・トーンを取り出す。
-- 既存の `DESIGN.md` と `styles.css` を読む。既にあるルールで今回触らないものは残す。
+- 既存の `styles.css` を読み、マーカーから今のテーマ名を確かめる。今回触らない上書きは残す。
+- プロジェクトルートに `DESIGN.md` があれば読む(ユーザー所有。書き換えない)。色の割り当てはテーマが優先。
 - スライド(`*.slide.tsx`)があるかを `ls` / `vantage routes` で確認しておく。
 
 ### 2. 提案して確認を取る
 
 書き込む前に、次の 2 つをユーザーに見せて確認を取る。
 
-- **役割 → トークンの対応表**(主色・強調・良い/悪い/注意・背景の段階・文字・チャート 5 色・書体)。
+- **役割 → トークンの対応表**(主色・背景の段階・文字・チャート 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` にしたいなど)は、マーカーブロックの**後ろ**に
+- **トーンの説明**(2〜3 行)。
+
+テーマで足りる場合はテーマ id(`references/presets.md`)で提案してよい。旧プリセット id(`default` / `calm` / `vivid` / `mono`)で頼まれたら新 id に読み替える。
+
+### 3. テーマを当て、styles.css を書く
+
+- **テーマ範囲・チャート範囲のマーカーの中は手で編集しない。** 色・角丸・書体の出発点は 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,13 +78,11 @@ 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>", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Hiragino Sans", "Hiragino Kaku Gothic ProN", "Noto Sans JP", Meiryo, ui-sans-serif, system-ui, sans-serif;
-     }
      :root {
+       --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);
      }
@@ -90,18 +93,15 @@ Vantage アプリの見た目は 2 つのファイルで決まる。
   `ui-sans-serif` / `system-ui` は日本語の face より**後ろ**に置く。日本語の Windows ではどちらも
   Yu Gothic UI(UI のリサイズを避けるために字幅を詰めた書体)に解決され、カナがここで決まって
   半角風に見える。macOS の Chrome は `-apple-system` を解釈しないので `BlinkMacSystemFont` も並べる。
-  既存アプリの `styles.css` に `ui-sans-serif, system-ui, …` が先頭にある、または `"Yu Gothic UI"` が
-  残っているときは、`body` の `font-family` を上の並びに直す(ほかの行は書き換えない)。
+  既存アプリの `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/` 配下のパスで「ブランド素材」行に書く。
-
 ### 4. コントラストを確かめる
 
 主な文字色 / 背景色の組を、**ライトとダークの両方で**確かめる。
@@ -131,11 +131,11 @@ node <このスキルの場所>/scripts/contrast.mjs '<文字色>' '<背景色>'
 npx vantage check
 ```
 
-`HARDCODED_COLOR`(ページ内の色コード)や `DESIGN_MD_TOO_LONG` が出たらその場で直す。
+`HARDCODED_COLOR`(ページ内の色コード)などが出たらその場で直す。
 
 ### 7. 完了を報告する
 
-報告には、更新したファイル(`DESIGN.md` / `styles.css`)に加えて次を**必ず**入れる。
+報告には、更新したファイル(`styles.css` など)と当てたテーマ名に加えて次を**必ず**入れる。
 
 - プレビューページのパスと URL(`src/design-preview.tsx` → `/design-preview`)。
 - 「ホームなど既存の画面は一部の色しか使っていないので、変更が見えないことがある。配色はプレビュー
@@ -143,5 +143,5 @@ npx vantage check
 
 ## 会話中の指示との関係
 
-- 会話中の個別の指示(「このグラフだけ赤で」)は `DESIGN.md` より優先する。そのページだけ直せばよい。
-- 同じ指示が 2 回以上出たら、`DESIGN.md` への反映を提案する(反映するときはこの手順の 2 から)。
+- 会話中の個別の指示(「このグラフだけ赤で」)はテーマより優先する。そのページだけ直せばよい。
+- 同じ指示が 2 回以上出たら、`styles.css` の上書きへ反映することを提案する(この手順の 2 から)。

package/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,14 +37,14 @@ 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 名。
 
 注意:
 
 - SPA で HTML がほぼ空のときは、`<script>` より先に CSS の `<link>` を探す。それも無ければ
   ユーザーにスクリーンショットかブランドカラーを聞く(推測で埋めない)。
 - 取得できない(認証・ボット対策)ときは、その旨を伝えてスクリーンショットをもらう。
-- ロゴを使うなら `public/brand/` に保存し、`DESIGN.md` の「ブランド素材」行にパスを書く。
+- ロゴを使うなら `public/brand/` に保存する。
 
 ## 画像・ロゴ
 
@@ -66,27 +67,26 @@ 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 などが書いたもの)
 
-外部の DESIGN.md は YAML frontmatter や本文に**値**(hex・px・フォント名)を持っていることが多い。
-Vantage の `DESIGN.md` は値を持たないので、**値を `styles.css` へ移し、`DESIGN.md` をトークン参照に
-書き直す**。
+外部の DESIGN.md が値(hex・px・フォント名)を持っているときは、値だけを拾って**テーマ側**へ移す。
+Vantage に `DESIGN.md` は作らない。
 
-1. 値を拾う: primary / secondary / surface / background / on-* / error / success / warning、
-   フォント、角丸。
+1. 値を拾う: primary / secondary / surface / background / on-* / error、フォント、角丸。
 2. 対応づける:
 
    | 外部の名前 | Vantage のトークン |
@@ -96,15 +96,14 @@ Vantage の `DESIGN.md` は値を持たないので、**値を `styles.css` へ
    | background / surface / surface-container | `--background` / `--card` / `--muted` |
    | on-background / on-surface / on-surface-variant | `--foreground` / `--card-foreground` / `--muted-foreground` |
    | outline | `--border` |
-   | error | `--destructive` |
-   | success / warning | 専用トークンなし → `--chart-*` のどれかに割り当てて `DESIGN.md` に書く |
+   | error | `--destructive`(意味トークンの negative) |
+   | success / warning | テーマの意味トークン(positive / warning)に任せる。チャートの色には割り当てない |
    | 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 に
-   ダークの値が無ければ、ライトの色相を保って明度だけ反転した値を作り、コントラストを確かめる。
-4. `DESIGN.md` を `format.md` の節の順番で書き直す。外部の文章(トーン・Do/Don't・コンポーネントの
-   ルール)は活かし、値だけをトークン名に置き換える。150 行に収まらない分は要約する。
-5. 元のファイルは消さずに残すか(例: `docs/design-source.md`)、ユーザーに確認して削除する。
+   (チャート色・書体の書き方は SKILL.md の手順 3)。外部にダークの値が無ければ、ライトの色相を保って
+   明度だけ反転した値を作り、コントラストを確かめる。
+4. 外部のトーン・Do/Don't・コンポーネントのルールは、ユーザーが望んだときだけ任意の `DESIGN.md`
+   (`format.md`)に要約して残す。値は書かない。