@squadbase/vantage-template 0.0.2 → 0.1.0-dev.3f759a0

package/base-template/.squadbase/skills/vantage-design/references/presets.md

@@ -0,0 +1,110 @@
+# 初期デザインのプリセット
+
+プロジェクト作成時に選ぶ 4 つの出発点。**id(`default` / `calm` / `vivid` / `mono`)はプロジェクト
+作成のワークフローが参照するので変えないこと。** どれも「チャートのプリセット 1 つ + `--primary` +
+`DESIGN.md` の差分」でできている。**`--primary` はどのプリセットでも必ず書く**(無彩色のプリセットも
+値を明示する)。チャートだけ変えるとホームのような色の少ない画面では見た目が変わらず、別のプリセットから
+切り替えたときに前の `--primary` が残るため。
+
+適用の手順は共通:
+
+1. `npx @squadbase/vantage-template chart <チャートのプリセット>` で `styles.css` のマーカーブロックを
+   差し替える。**マーカーブロックの中(`--chart-1..5`)は手で編集しない** ― コマンドの生成物で、
+   次の適用で消える。
+2. 各プリセットの `--primary` / `--primary-foreground` を、`styles.css` のマーカーの**外**(先頭の
+   `:root` ブロック)に `:root` と `.dark, [data-theme="dark"]` の両方で書く。既にある `--primary` は置き換える。
+3. `DESIGN.md` を `format.md` の雛形から作り、下の「DESIGN.md の差分」の行だけを書き換える。
+4. `scripts/contrast.mjs` で `--primary-foreground` / `--primary` をライトとダークで確かめる。
+
+| id | トーン | チャートのプリセット | `--primary` |
+| --- | --- | --- | --- |
+| `default` | 無彩色のベース。色を持つのはデータ(`blue` チャート)だけ | `blue` | 無彩色(`theme.css` の既定値を明示) |
+| `calm` | 落ち着いた寒色。報告書・経営向け | `ocean` | 深い青(スカイ 700 / 300) |
+| `vivid` | 明るい暖色。営業・マーケティング向け | `sunset` | 濃いオレンジ(オレンジ 700 / 400) |
+| `mono` | モノクロ。印刷・資料への貼り付け向け | `mono` | ジンク 900 / 200 |
+
+## `default`
+
+- トーン: 落ち着いた無彩色のベースに、データだけが色を持つ業務ダッシュボード。装飾より読みやすさ。
+- チャート: `blue`(青 → ティール → フクシア → バイオレット → グレー)。
+- `--primary`(フレームワークの既定と同じ無彩色。他のプリセットから戻すときのために明示する):
+
+  ```css
+  :root {
+    --primary: oklch(0.205 0 0);
+    --primary-foreground: oklch(0.985 0 0);
+  }
+  .dark,
+  [data-theme="dark"] {
+    --primary: oklch(0.922 0 0);
+    --primary-foreground: oklch(0.205 0 0);
+  }
+  ```
+
+- `DESIGN.md`: 雛形そのまま(`format.md` の雛形は `default` を説明している)。
+
+## `calm`
+
+- トーン: 寒色でまとめた静かな画面。強調は控えめにし、数字と罫線で読ませる。
+- チャート: `ocean`(スカイ → シアン → インディゴ → ティール → スレート)。
+- `--primary`(チャートのスカイに揃えた深い青):
+
+  ```css
+  :root {
+    --primary: var(--color-sky-700);
+    --primary-foreground: oklch(0.985 0 0);
+  }
+  .dark,
+  [data-theme="dark"] {
+    --primary: var(--color-sky-300);
+    --primary-foreground: oklch(0.205 0 0);
+  }
+  ```
+
+- `DESIGN.md` の差分: 「全体のトーン」を上の文に。チャートの色味を「スカイ → シアン → インディゴ →
+  ティール → スレート」に。良い = `--chart-4`(ティール)。1 系列の強調は `--chart-1` + 残り `--chart-5`。
+  禁止: `--chart-1` と `--chart-2` を隣り合う細い線で並べる(どちらも明るい青系)。
+
+## `vivid`
+
+- トーン: 明るく勢いのある暖色。KPI とトレンドを大きく見せ、強調色をはっきり使う。
+- チャート: `sunset`(オレンジ → アンバー → ローズ → イエロー → ストーン)。
+- `--primary`(オレンジ 600 は白文字で 4.5:1 に届かないので 700 を使う):
+
+  ```css
+  :root {
+    --primary: var(--color-orange-700);
+    --primary-foreground: oklch(0.985 0 0);
+  }
+  .dark,
+  [data-theme="dark"] {
+    --primary: var(--color-orange-400);
+    --primary-foreground: oklch(0.205 0 0);
+  }
+  ```
+
+- `DESIGN.md` の差分: トーンを上の文に。主色の行を「濃いオレンジ」に。良い = 専用色なし(▲ と
+  `--foreground`)、悪い = `--destructive`。禁止: `--chart-3`(ローズ)と `--destructive` を同じ
+  チャートに置く(悪い値と区別できない)。1 系列の強調は `--chart-1` + 残り `--chart-5`。
+
+## `mono`
+
+- トーン: 白黒と灰色だけ。色で意味を運ばず、太さ・順番・ラベルで読ませる。
+- チャート: `mono`(ジンク 900 → 200。ダークでは反転)。
+- `--primary`(チャートの両端と同じジンク):
+
+  ```css
+  :root {
+    --primary: var(--color-zinc-900);
+    --primary-foreground: oklch(0.985 0 0);
+  }
+  .dark,
+  [data-theme="dark"] {
+    --primary: var(--color-zinc-200);
+    --primary-foreground: oklch(0.205 0 0);
+  }
+  ```
+
+- `DESIGN.md` の差分: トーンを上の文に。強調 = `--chart-1`(最も濃い灰)。良い = 専用色なし(▲ と
+  符号)、悪い = `--destructive`(**画面で唯一の有彩色**として使う)。チャートは系列を 3 つまでにし、
+  それ以上は直接ラベルを付ける。禁止: 隣り合う `--chart-4` と `--chart-5`(明度差が小さい)。

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/.squadbase/skills/vantage-pitfalls/SKILL.md

@@ -35,6 +35,28 @@ Base UI の `SelectValue` は選択中の **value をそのまま描き**、`Sel
 
 トリガーに `kanto` や `/sales` と生の値が出たら、まずこれを疑う。
 
+## 配色:素のパレット + `dark:` ではなく、セマンティックトークンで書く
+
+色は `text-foreground` / `text-muted-foreground` / `bg-card` / `border-border` などの
+トークンで書く。トークンはライト / ダークの両方を持っているので、`dark:` を並べる必要が無い。
+
+`text-slate-900 dark:text-slate-100` のような素の Tailwind パレット + `dark:` の組は、
+**トークンで塗られた周囲と食い違う**。ダークトークンが効くのは祖先に `.dark` /
+`[data-theme="dark"]` が付いているときだけで、`dark:` ユーティリティも同じスイッチに
+繋がっている(`theme.css` の `@custom-variant dark`)。つまり自分でクラスを付けない限り
+アプリは常にライトで動くのに、素のパレットを使うとその 1 か所だけ手動で両モードを
+管理することになる。
+
+```tsx
+// ✗ 手動で 2 モードを管理することになる
+<div className="font-medium text-slate-900 dark:text-slate-100">{name}</div>
+// ✓ トークンなら 1 つで済む
+<div className="font-medium text-foreground">{name}</div>
+```
+
+`--muted` / `--accent` / `--secondary` / `--border` は**背景・境界用**で、ライトではほぼ白。
+文字色に使うと読めなくなる ― 弱い文字色は `text-muted-foreground`。
+
 ## チャート:`EChart` の配色はトークン追従。上書きは `option.color`
 
 系列色は `--chart-1..5`、軸・凡例・ツールチップは文字色/境界色のトークンから組まれる