@squadbase/vantage 0.6.2-dev1.d594c56 → 0.6.2-dev1.e85faec

package/registry/ui/waterfall-chart.tsx

@@ -32,7 +32,7 @@ import { EChart } from "@squadbase/vantage/components"
 import type { Polarity } from "@squadbase/vantage/components"
 import { EMPTY_VALUE, MINUS_SIGN } from "@squadbase/vantage/components"
 import type { ChartCommonProps, NumericKeys, ValueFormatter } from "@squadbase/vantage/components"
-import { createContext, useCallback, useEffect, useRef, useState } from "react"
+import { createContext, useCallback, useEffect, useRef, useState, type RefObject } from "react"
 import type { ChartTone } from "@squadbase/vantage/components"
 import { type ReactNode } from "react"
 import { computeComparison, defaultChangeDisplay, formatChange, toneForValue, type ComparisonKind, type PeriodGrain } from "@squadbase/vantage/components"
@@ -65,6 +65,8 @@ const SERIES_TOKENS = ["--chart-1", "--chart-2", "--chart-3", "--chart-4", "--ch
 interface ChartTokens {
   /** Resolved `--chart-1..5`, in order. */
   series: string[]
+  /** Computed `font-family` of the container, so canvas text matches the DOM. Optional. */
+  fontFamily?: string
   /** Body text: titles and the default `textStyle`. */
   foreground: string | null
   /** Secondary text: axis labels, legend, subtitles. */
@@ -73,10 +75,23 @@ interface ChartTokens {
   border: string | null
   /** Tooltip surface. */
   popover: string | null
+  /** Semantic and surface dependencies used by typed chart options. Optional for hand-built tokens. */
+  colors?: Record<string, string>
+  /** Actual inherited painting surface (may change without a token changing). */
+  surface?: string | null
   /** Tooltip text. */
   popoverForeground: string | null
 }
 
+// Keep scope out of the public token shape. A resolved snapshot remembers where arbitrary
+// var(--token) expressions must be read, without retaining unmounted charts globally.
+const tokenScopes = new WeakMap<ChartTokens, Element>()
+const OPTION_COLOR_TOKENS = [
+  "--background", "--card", "--muted", "--primary", "--destructive",
+  ...["positive", "negative", "warning", "neutral", "info"].flatMap((tone) =>
+    ["", "-fill", "-subtle"].map((suffix) => `--${tone}${suffix}`)),
+]
+
 let normalizeContext: CanvasRenderingContext2D | null | undefined
 
 /** The forms `fillStyle` serializes legacy colours to, and zrender can parse. */
@@ -132,14 +147,19 @@ function readChartTokens(el?: Element | null): ChartTokens | null {
     const color = read(token)
     if (color) series.push(color)
   }
-  return {
+  const tokens: ChartTokens = {
     series,
+    colors: Object.fromEntries(OPTION_COLOR_TOKENS.map((name) => [name, styles.getPropertyValue(name).trim()])),
+    surface: readChartSurface(target),
+    ...(styles.fontFamily ? { fontFamily: styles.fontFamily } : {}),
     foreground: read("--foreground"),
     mutedForeground: read("--muted-foreground"),
     border: read("--border"),
     popover: read("--popover"),
     popoverForeground: read("--popover-foreground"),
   }
+  tokenScopes.set(tokens, target)
+  return tokens
 }
 
 /** Structural equality, so a theme toggle that changes nothing doesn't re-init. */
@@ -147,8 +167,13 @@ function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean
   if (a === b) return true
   if (!a || !b) return false
   return (
+    tokenScopes.get(a) === tokenScopes.get(b) &&
+    a.surface === b.surface &&
+    Object.keys(a.colors ?? {}).length === Object.keys(b.colors ?? {}).length &&
+    Object.entries(a.colors ?? {}).every(([name, value]) => b.colors?.[name] === value) &&
     a.series.length === b.series.length &&
     a.series.every((color, i) => color === b.series[i]) &&
+    a.fontFamily === b.fontFamily &&
     a.foreground === b.foreground &&
     a.mutedForeground === b.mutedForeground &&
     a.border === b.border &&
@@ -171,7 +196,7 @@ function sameChartTokens(a: ChartTokens | null, b: ChartTokens | null): boolean
  *    attributes alone leaves the chart painted in the previous palette until a
  *    reload — the tokens in the DOM are new, the canvas is not.
  */
-function watchChartTokens(onChange: () => void): () => void {
+function watchChartTokens(onChange: () => void, scope?: Element | null): () => void {
   if (typeof document === "undefined") return () => {}
   // Style edits arrive as bursts of mutations; coalesce them into one read, and
   // take it after the next frame so a swapped stylesheet has been applied.
@@ -186,8 +211,11 @@ function watchChartTokens(onChange: () => void): () => void {
 
   const themeObserver = new MutationObserver(schedule)
   const attributeFilter = ["class", "style", "data-theme"]
-  themeObserver.observe(document.documentElement, { attributes: true, attributeFilter })
-  if (document.body) themeObserver.observe(document.body, { attributes: true, attributeFilter })
+  // Only the chart and its ancestors can change its inherited theme. Never observe
+  // the document subtree: canvas/tooltip/rendering mutations would trigger every chart.
+  for (let node: Element | null = scope ?? document.body ?? document.documentElement; node; node = node.parentElement) {
+    themeObserver.observe(node, { attributes: true, attributeFilter })
+  }
 
   const styleObserver = new MutationObserver(schedule)
   if (document.head) {
@@ -243,7 +271,7 @@ function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
     // Let the page background show through: charts sit on cards, not on a canvas.
     backgroundColor: "transparent",
     ...(tokens.series.length > 0 ? { color: tokens.series } : {}),
-    textStyle: { color: text },
+    textStyle: { color: text, ...(tokens.fontFamily ? { fontFamily: tokens.fontFamily } : {}) },
     title: { textStyle: { color: text }, subtextStyle: { color: muted } },
     legend: { textStyle: { color: muted } },
     categoryAxis: axisTheme(tokens, false),
@@ -259,7 +287,11 @@ function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
       padding: [8, 12],
       // Rounded card with a soft shadow; in dark mode the shadow barely shows, so the border carries the edge.
       extraCssText: "border-radius:8px;box-shadow:var(--shadow-card, 0 4px 12px rgb(0 0 0 / 0.08));",
-      textStyle: { color: tokens.popoverForeground ?? undefined, fontSize: 12 },
+      textStyle: {
+        color: tokens.popoverForeground ?? undefined,
+        fontSize: 12,
+        ...(tokens.fontFamily ? { fontFamily: tokens.fontFamily } : {}),
+      },
       axisPointer: { lineStyle: { color: line }, crossStyle: { color: line } },
     },
   }
@@ -271,22 +303,23 @@ function buildChartTheme(tokens: ChartTokens): Record<string, unknown> {
  * components that build an ECharts option from token colours themselves (the
  * typed charts), so their palette follows light/dark like `EChart`'s theme.
  */
-function useChartTokens(): ChartTokens | null {
+function useChartTokens(scope?: Element | null | RefObject<Element | null>): ChartTokens | null {
   const [tokens, setTokens] = useState<ChartTokens | null>(() => readChartTokens())
   // Compared here, not inside a `setTokens` updater: an updater that reads the DOM is
   // replayed by React on every rebase and returns a fresh object each time, so the state
   // never settles ("Maximum update depth exceeded" once the tokens change after mount).
   const tokensRef = useRef(tokens)
   useEffect(() => {
+    const target = scope && "current" in scope ? scope.current : scope
     const sync = () => {
-      const next = readChartTokens()
+      const next = readChartTokens(target)
       if (sameChartTokens(tokensRef.current, next)) return
       tokensRef.current = next
       setTokens(next)
     }
     sync()
-    return watchChartTokens(sync)
-  }, [])
+    return watchChartTokens(sync, target)
+  }, [scope])
   return tokens
 }
 
@@ -298,7 +331,7 @@ const EMBEDDED_VAR_RE = /var\(\s*(--[\w-]+)\s*\)/g
 /**
  * Turn chart colours into canvas-safe strings. `"chart-1"`〜`"chart-5"` come from
  * the resolved series tokens; `"positive"` / `"warning"` / `"negative"` / `"neutral"` (and the area
- * variants `"positive-fill"`, …) are read off the document root (`--positive`, …); `var(--token)` is read off the document root; any
+ * variants `"positive-fill"`, …) are read in the snapshot's inherited scope (`--positive`, …); `var(--token)` uses the same scope; any
  * other CSS colour is normalized like the tokens are. A colour that can't be
  * resolved comes back as `""`, which ECharts treats as "use the palette".
  */
@@ -309,12 +342,13 @@ function resolveChartColors(colors: readonly string[], tokens: ChartTokens | nul
     // Meaning colours are the theme tokens of the same name: same path as `var(--positive)`.
     if (TONE_NAME_RE.test(color.trim())) {
       if (typeof document === "undefined") return ""
-      return toCanvasColor(getComputedStyle(document.documentElement).getPropertyValue(`--${color.trim()}`)) ?? ""
+      const target = (tokens && tokenScopes.get(tokens)) ?? document.documentElement
+      return toCanvasColor(getComputedStyle(target).getPropertyValue(`--${color.trim()}`)) ?? ""
     }
     if (typeof document === "undefined") return color
     let value = color.trim()
     const cssVar = CSS_VAR_RE.exec(value)
-    const styles = getComputedStyle(document.documentElement)
+    const styles = getComputedStyle((tokens && tokenScopes.get(tokens)) ?? document.documentElement)
     if (cssVar) {
       value = styles.getPropertyValue(cssVar[1]!).trim() || (cssVar[2] ?? "").trim()
     } else if (value.includes("var(")) {
@@ -360,7 +394,7 @@ function readChartSurface(el: Element | null): string | null {
       if (color) return color
     }
   }
-  return toCanvasColor(getComputedStyle(document.documentElement).getPropertyValue("--background"))
+  return toCanvasColor(getComputedStyle(el ?? document.documentElement).getPropertyValue("--background"))
 }
 
 /** Widths are bucketed so a resize only rebuilds the option when the label budget can change. */
@@ -374,9 +408,10 @@ const WIDTH_BUCKET = 40
  */
 function useChartSurface<E extends Element>(
   forwarded: ForwardedRef<E>,
-  tokens: ChartTokens | null,
-): { ref: (el: E | null) => void; surface: string | undefined; width: number | undefined } {
+  tokens?: ChartTokens | null,
+): { ref: (el: E | null) => void; surface: string | undefined; width: number | undefined; tokens: ChartTokens | null } {
   const [node, setNode] = useState<E | null>(null)
+  const scopedTokens = useChartTokens(node)
   const [surface, setSurface] = useState<string | undefined>(undefined)
   const [width, setWidth] = useState<number | undefined>(undefined)
   const ref = useCallback(
@@ -390,7 +425,7 @@ function useChartSurface<E extends Element>(
   useEffect(() => {
     if (!node) return
     setSurface(readChartSurface(node) ?? undefined)
-  }, [node, tokens])
+  }, [node, tokens, scopedTokens])
   useEffect(() => {
     if (!node || typeof ResizeObserver === "undefined") return
     const update = (w: number) => setWidth(Math.floor(w / WIDTH_BUCKET) * WIDTH_BUCKET)
@@ -399,7 +434,7 @@ function useChartSurface<E extends Element>(
     observer.observe(node)
     return () => observer.disconnect()
   }, [node])
-  return { ref, surface, width }
+  return { ref, surface, width, tokens: scopedTokens }
 }
 
 /* ---------- inlined from @squadbase/squadkit registry/lib/chart-options.ts (internal to @squadbase/vantage) ---------- */
@@ -789,6 +824,10 @@ const toDate = (t: ParsedTime) => new Date(t.year, t.month - 1, t.day)
 
 /** How many x labels a time axis shows at most (the step is picked so the labels never crowd). */
 const TIME_AXIS_MAX_LABELS = 6
+/** Under this plot width (px) the axis, legend and labels switch to their compact form. */
+const NARROW_PLOT_WIDTH = 400
+/** The most x labels a narrow plot shows (a 262px plot reads 4 at most). */
+const NARROW_TIME_AXIS_MAX_LABELS = 4
 
 /** Calendar-friendly label steps per granularity (every 3 months, every week …). */
 const TIME_AXIS_STEPS: Record<TimeGranularity, readonly number[]> = {
@@ -1234,7 +1273,9 @@ const LEGEND_LINE_BUDGET = 320
 /** How many lines the plain legend takes, estimated from its labels (12px text + 8px dot + gaps). */
 function legendLines(items: readonly string[], plotWidth?: number, reserve = 0): number {
   const width = items.reduce((sum, name) => sum + [...name].length * 12 + 8 + 5 + 16, 0)
-  const budget = Math.max(80, (plotWidth ? Math.min(LEGEND_LINE_BUDGET, plotWidth) : LEGEND_LINE_BUDGET) - reserve)
+  // A narrow plot has no room for the PNG buttons beside the legend: they move off its line, so no reserve.
+  const narrow = plotWidth !== undefined && plotWidth < NARROW_PLOT_WIDTH
+  const budget = Math.max(80, (plotWidth ? (narrow ? plotWidth : Math.min(LEGEND_LINE_BUDGET, plotWidth)) : LEGEND_LINE_BUDGET) - (narrow ? 0 : reserve))
   return Math.min(3, Math.max(1, Math.ceil(width / budget)))
 }
 
@@ -1489,7 +1530,15 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
     ? null
     : timeAxisLabelStep(
         rawIndex,
-        plotWidth ? Math.max(2, Math.min(TIME_AXIS_MAX_LABELS, Math.floor(plotWidth / TIME_LABEL_WIDTH))) : undefined,
+        plotWidth
+          ? Math.max(
+              2,
+              Math.min(
+                plotWidth < NARROW_PLOT_WIDTH ? NARROW_TIME_AXIS_MAX_LABELS : TIME_AXIS_MAX_LABELS,
+                Math.floor(plotWidth / TIME_LABEL_WIDTH),
+              ),
+            )
+          : undefined,
       )
   // Plain (non-date) x labels of a line chart: thinned to every n-th so they never touch, never rotated.
   const plainStep = (() => {
@@ -1535,8 +1584,12 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
           : []
   // On a narrow plot the max and the latest label would print over each other: keep the latest.
   const pointGap = plotWidth && labels.length > 1 ? plotWidth / (kind === "bar" ? labels.length : labels.length - 1) : null
+  // By default only the latest value is labelled; an explicit `highlight` keeps its max + latest.
+  const latestOnly = cfg.highlight === undefined && !shareHighlight && picked.length === 2
   const highlightPoints =
-    picked.length === 2 && pointGap !== null && Math.abs(picked[1]!.index - picked[0]!.index) * pointGap < HIGHLIGHT_LABEL_WIDTH
+    latestOnly
+      ? [picked[1]!]
+      : picked.length === 2 && pointGap !== null && Math.abs(picked[1]!.index - picked[0]!.index) * pointGap < HIGHLIGHT_LABEL_WIDTH
       ? [picked[1]!]
       : picked
 
@@ -1747,6 +1800,8 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
           ? { width: 0, color, opacity: 0 }
           : { width: 2, color, opacity: dimSeries ? DIMMED : 1 },
       itemStyle: { color, opacity: dimSeries ? DIMMED : 1 },
+      // Hovering a series fades the others (not for a stack, where the bands read together).
+      emphasis: stacked ? undefined : { focus: "series" as const },
       areaStyle: areaStyle && dimSeries ? { ...areaStyle, opacity: DIMMED * 0.3 } : areaStyle,
       markPoint: markPointFor(c, color),
       markLine: undefined,
@@ -2193,7 +2248,10 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
     legend: {
       show: showLegend,
       top: 0,
-      right: reserveActions ? ACTIONS_RESERVE : 0,
+      // Narrow: left-aligned and wrapping above the plot, so nothing is cut off at the right edge.
+      ...(plotWidth !== undefined && plotWidth < NARROW_PLOT_WIDTH
+        ? { left: 0, right: 0 }
+        : { right: reserveActions ? ACTIONS_RESERVE : 0 }),
       // Plain wraps onto a second line at narrow widths instead of hiding items behind arrows.
       type: "plain",
       icon: "circle",
@@ -2254,7 +2312,12 @@ function buildCartesianOption(cfg: CartesianChartConfig): EChartsOption {
           }
         }
         const shares = percent ? cartesianSeriesValues(i <= lastActual ? [row] : [], categories, "percent") : null
-        for (const p of list) {
+        // Rows follow the legend order (categories first), not ECharts' own series order.
+        const legendRank = (p: AxisTooltipParam) => {
+          const at = categories.indexOf(p.seriesName ?? "")
+          return at === -1 ? categories.length : at
+        }
+        for (const p of [...list].sort((a, b) => legendRank(a) - legendRank(b))) {
           const color = typeof p.color === "string" ? p.color : "currentColor"
           if (p.seriesId === FORECAST_SERIES_ID) {
             // At and before the boundary the forecast repeats the actual value.
@@ -4105,8 +4168,7 @@ function WaterfallChartImpl<T extends Record<string, unknown>>(
   ref: ForwardedRef<HTMLDivElement>,
 ) {
   const valueKey: string = categories[0] ?? ""
-  const tokens = useChartTokens()
-  const { ref: frameRef, width: plotWidth } = useChartSurface(ref, tokens)
+  const { ref: frameRef, width: plotWidth, tokens } = useChartSurface(ref)
   // Value labels and the tooltip read in full (as `format` says); ticks read short.
   const valueFormatter = useMemo(() => resolveValueFormatter(valueFormatterProp, format), [valueFormatterProp, format])
   const axisFormatter = useMemo(() => resolveAxisFormatter(valueFormatterProp, format), [valueFormatterProp, format])

package/skills/vantage-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vantage-design
-description: Vantage(@squadbase/vantage)アプリの見た目の意図 `DESIGN.md` と、実際の値を持つ `styles.css` をまとめて作る / 更新する手順。配色・ブランドカラー・テーマ・チャートの色・フォント・角丸・トーンを変えたいとき、既存サイトやロゴ・資料・外部の DESIGN.md に合わせたいとき、プロジェクト作成時の初期デザイン(プリセット default / calm / vivid / mono)を決めるときに使う。「色を変えて」「ブランドに合わせて」「このサイトに合わせて」「落ち着いた感じに」「フォントを変えて」「テーマを作って」「DESIGN.md を作って」、"change the colors", "match our brand", "match this website", "theme", "color palette", "font", "design system", "DESIGN.md" で起動。
+description: Vantage(@squadbase/vantage)アプリの見た目の意図 `DESIGN.md` と、実際の値を持つ `styles.css` をまとめて作る / 更新する手順。配色・ブランドカラー・テーマ・チャートの色・フォント・角丸・トーンを変えたいとき、既存サイトやロゴ・資料・外部の DESIGN.md に合わせたいとき、プロジェクト作成時の初期デザイン(テーマ neutral / ocean / forest / sunset / violet / rose / mono)を決めるときに使う。「色を変えて」「ブランドに合わせて」「このサイトに合わせて」「落ち着いた感じに」「フォントを変えて」「テーマを作って」「DESIGN.md を作って」、"change the colors", "match our brand", "match this website", "theme", "color palette", "font", "design system", "DESIGN.md" で起動。
 ---
 
 # DESIGN.md と styles.css をまとめて更新する
@@ -23,7 +23,7 @@ Vantage アプリの見た目は 2 つのファイルで決まる。
 | --- | --- |
 | `references/format.md` | `DESIGN.md` を書く / 直すとき(書式・節の順番・雛形) |
 | `references/extract.md` | URL・画像・pptx/pdf・言葉・外部 DESIGN.md から色と書体を取り出すとき |
-| `references/presets.md` | プロジェクト作成時の初期デザイン(`default` / `calm` / `vivid` / `mono`) |
+| `references/presets.md` | テーマ(`neutral` / `ocean` / `forest` / `sunset` / `violet` / `rose` / `mono`)の選び方と `theme` コマンド。旧プリセット id の読み替え |
 | `scripts/contrast.mjs` | 文字色と背景色のコントラスト比を確かめるとき |
 
 ## 手順
@@ -43,29 +43,32 @@ Vantage アプリの見た目は 2 つのファイルで決まる。
   各行に「何に合わせてその色にしたか」を 1 語添える。
 - **トーンの説明**(2〜3 行。`DESIGN.md` の「全体のトーン」にそのまま入る文)。
 
-プリセットで足りる場合はプリセット名(`references/presets.md`)で提案してよい。
+テーマで足りる場合はテーマ id(`references/presets.md`)で提案してよい。旧プリセット id(`default` / `calm` / `vivid` / `mono`)で頼まれたら新 id に読み替える。
 
 ### 3. styles.css と DESIGN.md を同じステップで書く
 
 `styles.css`:
 
-- **マーカーブロックの中は手で編集しない。**
-  ``/* vantage-template:chart-preset — regenerated by `chart`; edits here are lost */`` 〜
-  `/* vantage-template:chart-preset:end */` の間はコマンドが丸ごと書き換える生成物で、手で直した
-  値は次の適用で消える。
-- チャートの 5 色は必ずコマンドで選ぶ: `npx @squadbase/vantage-template chart <preset>`
-  (`blue` / `ocean` / `sunset` / `forest` / `berry` / `mono`。プロジェクトルートで実行。
-  `--dry-run` で書き込まずに結果を見られる)。マーカーの中だけが置き換わり、他の記述は残る。
-- プリセットに無いチャート色(ブランド色を `--chart-1` にしたいなど)は、マーカーブロックの**後ろ**に
+- **テーマ範囲・チャート範囲のマーカーの中は手で編集しない。** 色・角丸・書体の出発点は 7 テーマ
+  (`neutral` / `ocean` / `forest` / `sunset` / `violet` / `rose` / `mono`)から選び、コマンドで当てる:
+  `npx @squadbase/vantage-template theme <id>`(プロジェクトルートで実行。`--dry-run` で書き込まずに
+  結果を見られる)。``/* squadkit-theme — regenerated by `theme`; edits here are lost */`` 〜
+  `/* squadkit-theme:end */` の間はコマンドが丸ごと書き換える生成物で、手で直した値は次の適用で消える。
+  旧プリセット id(`default` → `neutral` / `calm` → `ocean` / `vivid` → `sunset` / `mono`)もコマンドが受ける。
+- チャートの 5 色はテーマが持つ。テーマと別の配色にしたいときだけ
+  `npx @squadbase/vantage-template chart <preset>`(`blue` / `ocean` / `sunset` / `forest` / `berry` / `mono`)を使う。
+  ``/* vantage-template:chart-preset … */`` 〜 `/* vantage-template:chart-preset:end */` の間が置き換わり、
+  テーマのチャート色より優先される。テーマに揃え直すには `theme <id> --reset-chart`。
+- プリセットに無いチャート色(ブランド色を `--chart-1` にしたいなど)は、**マーカーブロックの後ろ**に
   別の `:root { --chart-1: …; }` と `.dark, [data-theme="dark"] { --chart-1: …; }` を足して上書きする
-  (後に書いた方が勝つ)。上書きするのは変えたい番号だけにし、残りはプリセットに任せる。
-- `--primary` / `--primary-foreground` / `--radius` などチャート以外のトークンは、マーカーの**外**
-  (ファイル先頭の `:root` ブロック)に書く。色は `:root` と `.dark, [data-theme="dark"]` の
-  **両方**に書く。片方だけだとダークモードで既定に戻る。値は `oklch()` か Tailwind のパレット変数
-  (`var(--color-sky-600)`)で書く。
-- 書体は既定でシステムフォント。**ページの書体を決めるのは `body` セレクタの `font-family`**
-  (フレームワークの `theme.css` が `body` にシステムフォントを直接指定しているため、`:root` や
-  `html` に `font-family` を書いても本文には効かない)。スライドの書体は `:root` の
+  (後に書いた方が勝つ)。上書きするのは変えたい番号だけにし、残りはテーマに任せる。
+- `--primary` / `--primary-foreground` / `--radius` などテーマに無い値・ブランド色の上書きも、
+  **マーカーブロックの後ろ**(ファイル末尾)に書く。マーカーより前に書いた値はテーマに負ける。
+  色は `:root` と `.dark, [data-theme="dark"]` の**両方**に書く。片方だけだとダークモードでテーマの値に
+  戻る。値は `oklch()` か Tailwind のパレット変数(`var(--color-sky-600)`)で書く。
+- 書体は既定でシステムフォント。**ページの書体は `--font-sans`**(`styles.css` の `body` が
+  `font-family: var(--font-sans)` で参照する。テーマ範囲も `--font-sans` を持つので、書体を変えるには
+  マーカーブロックの後ろで `:root { --font-sans: …; }` を上書きする)。スライドの書体は `:root` の
   `--slide-font-display`(見出し)/ `--slide-font-body`(本文)で決まる。Web フォントを使うときの
   レシピ:
   1. Google Fonts の CSS
@@ -73,13 +76,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,8 +91,9 @@ 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` 参照)。
 

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

package/skills/vantage-design/references/format.md

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