🎨 全コンポーネントを新セマンティックトークンへ移行（beta）

[touyou]

概要

デザイン側でカラートークンのセマンティックレイヤーが刷新されたため、全コンポーネントを新しいセマンティックトークンへ移行する。

未リリースのスタイル更新のため、beta チャネルでリリースする（gh workflow run "Publish to npm" の channel: beta）。

前提として sparkle-design-cli 側のトークン生成対応と beta リリースが先行する。

トラッキング: goodpatch/sparkle-design-internal#247

新しいセマンティックトークン体系

用途カテゴリ × 意味 × 強度 × 状態の 4 軸構成。状態（enabled / hover / active / disabled）がトークン名に内包されるのが最大の変更点。

• surface（背景）: base/0,100,200 / neutral|primary|negative × high|middle|low × enabled|hover|active|disabled / info|success|warning × high|middle|low / accent/1..3 / inverse / overlay
• border（枠線）: neutral × extra-high(enabled/hover/disabled)|high|middle|low / primary × extra-high|high|low / negative × extra-high(enabled/hover/disabled)|high|low / info|success|warning / ring
• object（アイコン等）: neutral × high|middle|low|disabled / primary|negative × enabled|hover|disabled / info|success|warning / inverse
• text: neutral × high|middle|low|disabled / primary|negative × enabled|hover|disabled / info|success|warning / inverse

CSS 変数名はデザイン側のパス構造をそのまま写す（surface/primary/high/enabled → --color-surface-primary-high-enabled）。

テーマ切り替えとの関係

• primary と名の付くトークンが primary 設定に追従する
• --color-border-ring は 青系固定で primary には追従しない
• info / success / warning はステータス色なので固定色相

主な置換パターン

旧	新
bg-white（背景）	surface/base/0
text-white（文字・アイコン）	text/inverse / object/inverse
text-text-{high,middle,low,disabled}	text/neutral/{high,middle,low,disabled}
text/placeholder	text/neutral/low
ring-normal	border/ring
border-divider-{low,middle,high}	border/neutral/{low,middle,high}
bg-primary-{500,600,700,200}	surface/primary/high/{enabled,hover,active,disabled}
bg-primary-{50,100}	surface/primary/low/{hover,active}
border-neutral-{500,600}	border/neutral/extra-high/{enabled,hover}
secondary-700（アイコン）	object/neutral/middle
skeleton-fill	surface/base/200
black-alpha-300	surface/overlay
neutral-900（背景）	surface/inverse

secondary カテゴリは廃止見込み（用途に応じて object/neutral/* / text/neutral/* に分岐）。

対象コンポーネント（24）

Button, Icon Button, Input, Input Password, Checkbox, Radio, Select, Switch, Slider, Textarea, Form,
Badge, Card, Divider, Tag, Inline Message, Skeleton, Spinner, Dialog, Modal, Overlay, Toast, Tooltip,
Tabs, Breadcrumb, Link, Icon

スタイル置換に留まらない構造変更（要注意）

デザイン側の指示には、単なるトークン差し替えでない変更が含まれる:

• 枠線の削除: Button / Icon Button の solid バリアントの 1px 枠線、Switch のトラック枠線（12 件）、Badge の白枠線
• シャドウの差し替え: Card（enable/hover: raise→flat、active: float→raise）、Slider disabled（raise→none）、Button（raise→base）
• 角丸の変更: Card（minimum→container）、Clickable Card の Focus Ring（値は 8px で不変）
• トークン統合: Input 系の text/disabled + neutral/400 → text/neutral/disabled

角丸のセマンティック名も halfModal → container にリネームされる（--radius-halfModal は beta 期間の後方互換エイリアスとして残る）。

旧トークンは beta 期間併存

--color-{semantic}-{50..900} / --color-text-* / --color-divider-* / --color-skeleton-fill / --color-ring-normal は beta 期間中そのまま利用可能。コンポーネントを順次移行し、beta 終了時に旧トークン削除 PR を別途立てる。

現行コードの旧語彙使用状況（src/components/ui）

41 bg-white     33 text-white   21 border-negative-500   18 bg-neutral-50
17 bg-primary-500   13 text-text-low   13 ring-normal   13 text-neutral-700
11 text-text-high    8 text-text-middle   8 text-text-disabled   8 shadow-raise
 7 border-divider-middle

置換対象は広範。ユーティリティクラス名の機械置換だけでは足りず、状態別クラス（hover: / disabled:）の再構成が必要。

#274（React 19 ref-as-prop）との関係

#274 は「他の大規模アップデートと同時にまとめてリリース」する前提で塩漬けされている PR で、今回の beta サイクルがまさにその機会。

ただし現在 CONFLICTING（DIRTY） かつ最終更新が 2026-05-19 で、main が 2.5 ヶ月分進んでいる。本 issue のトークン移行は #274 と同じ 17 ファイルを大幅に書き換えるため、順序で手戻り量が変わる。

方針: #274 を先に main へ追従させ（amend + force-push は規約で禁止のため、コンフリクト解決コミットを積む）、React 19 化を beta の土台にしてからトークン移行を載せる。

[touyou]

進捗（2026-08-17）

Figma に刷新済みページがあるコンポーネントの移行が完了（PR #303 のマージ待ち）。

マージ済み

PR	内容
#299	新セマンティックトークン 210 件 + --radius-container を生成 CSS に取り込み、build:css を sparkle-design-cli@beta へ、Vercel ビルドの CSS 生成を build:css に委譲
#300	状態非依存の旧トークンを一括リネーム（32 ファイル）
#301	Divider / Link / Inline Message / Form
#302	Input / Textarea / Tag

レビュー待ち

PR	内容
#303	Button / Icon Button（各 45 パターン）。solid の 1px 枠線削除・shadow-raise → shadow-base・hover でテキスト/アイコンが 1 段暗くなる挙動を含む

分割方針の変更

当初の A→B→C→D 分割は Figma 未反映のコンポーネントが混ざるため破棄し、「Figma に刷新済みページがあるか」で切る方針に変更した。刷新済み Figma ファイル（7alBZXZf65YgcII41TWT0r）にページがあるのは以下の 13 コンポーネントのみ:

Button / Form / Icon Button / Input / Input Date / Textarea / Divider / Table / Tag / Inline Message / Modal / Link / Icon

ブロック中（Figma 側の更新が未マージ）

以下は刷新済み Figma ファイルにページ自体が存在しないため着手できない。search_design_system では Card / Switch がヒットするが、これは別ライブラリの旧版（2025-11〜2026-01 更新）なので参照してはいけない。

Checkbox / Radio / Select / Switch / Slider / Badge / Card / Skeleton / Spinner / Dialog / Overlay / Toast / Tooltip / Tabs / Breadcrumb

main に残る旧トークン数（src/components/ui/*/index.tsx、#303 マージ後）:

tabs 25 / checkbox 22 / select 15 / radio 15 / switch 12
slider 10 / card 6 / tooltip 3 / badge 2 / toast 1 / breadcrumb 1

→ デザイナーに未反映コンポーネントの Figma 更新予定を確認する必要がある。

調査で判明した非自明な事実（次に触る人向け）

• 仕様取得は get_variable_defs を使う。get_design_context は Code Connect が効いていて既存コンポーネントのコードを返すだけで、色が取れない
• 🎨 feat: 新セマンティックトークンを生成 CSS に取り込む（beta / #298 フェーズ1） #299 は「見た目が変わらない」わけではない。プリミティブ配色 50 値とシャドウ全段が置き換わっているので、未移行コンポーネントも色・影が変わる（Figma 刷新の意図どおりだが、beta 中の見え方として認識が必要）
• Figma は状態のレベルを 1 段ずらした（旧: 通常 500 / hover 600 → 新: enabled 600 / hover 700）。hover:bg-primary-600 を機械的に置換すると色が変わる
• --color-neutral-* は --color-gray-* のエイリアスなので、neutral → gray 系の置換では色が変わらない
• ユーティリティ名は用途名が重なる（--color-border-neutral-low → border-border-neutral-low）。気持ち悪いが正しい
• bot レビューは鵜呑みにしない。🎨 refactor: Input / Textarea / Tag を Figma 準拠の新トークンへ移行（beta / #298 フェーズ2-3） #302 で CodeRabbit が「Tag の outline 枠線は border/* を使うべき」と Major 指摘したが誤り（Figma は object/* を bind しており、border/* にすると neutral が L=0.449 → 0.889 で激変する）。命名規則からの推論だった。必ず Figma の実バインディングと解決値で検証すること

別途起票が必要

• IconButton が children を分割代入しながらレンダリングしていないため asChild が実質機能していない（main 側にも同じコードあり・未起票）

[touyou]

引き継ぎメモ（worktree の HANDOFF-298.md から移設）

作業用 worktree に置いていた引き継ぎファイルを、この issue に集約する。以降はここが引き継ぎの正。

---

1. 現在地（2026-08-18）

Figma に刷新済みページがあるコンポーネントの移行はすべて完了した。

PR	merge commit	内容
#299	5ef9632	新セマンティックトークン 210 件 + --radius-container、build:css を @beta へ、Vercel スクリプト修正（0c09e8a）
#300	4e931d9	状態非依存トークンの一括リネーム（32 ファイル）
#301	f381683	Divider / Link / Inline Message / Form
#302	5ff1686	Input / Textarea / Tag
#303	e8d03e9	Button / Icon Button（各 45 パターン）。solid の 1px 枠線削除 / shadow-raise → shadow-base / hover でテキスト・アイコンが 1 段暗くなる

次にやること

デザイナーに未反映コンポーネントの Figma 更新予定を確認する。 これが解けるまで sparkle-design の残りは進められない（詳細は §4）。

その先は goodpatch/sparkle-design-internal#247 のリリース順序に従って internal（goodpatch/sparkle-design-internal#246）/ theme-settings / cli の migrate サブコマンドへ。

デザイナーに確認したい点（#303 は Figma のまま実装してある）

• Icon Button outline / ghost の primary だけ hover でアイコン色が変わらない（object/primary/enabled のまま）。neutral は object/neutral/high、negative は object/negative/hover に変わるので primary だけ非対称
• Button outline / ghost neutral の disabled 背景がプリミティブ white-alpha/700 を直接 bind している（他はすべて surface/*/low/disabled）。解決値は同一なのでセマンティック側を使った

移行中に見つかった既存バグ（起票済み・移行とは独立）

• 🐛 IconButton の asChild が機能していない（children がレンダリングされない） #304: IconButton の asChild が children をレンダリングしていない
• 🐛 IconButton に native の disabled prop を渡すと無効状態のスタイルが当たらない #305: IconButton の disabled 状態の CVA 条件が不揃い（native disabled prop が CVA に渡らない / outline primary・neutral に isDisabled: false が無く無効時に hover が効く）

---

2. 確立した手順（この手順で 5 PR 通している）

1. get_metadata でページ → component set → 各バリアントのノード ID を取得
2. get_variable_defs を各バリアントノードに対して呼ぶ。get_design_context は Code Connect が効いていて既存コンポーネントのコードを返すだけなので色が取れない
3. 返ってきた surface/* border/* object/* text/* をそのまま CSS 変数名に写す（surface/primary/high/enabled → --color-surface-primary-high-enabled → bg-surface-primary-high-enabled）
4. 旧新の解決値を突き合わせて「値が変わるか」を機械判定する（スクリプトは下記）
5. tsc --noEmit と vitest run --project unit を通す。テストのアサーションも追従させる
6. prettier をかけてコミット → push → PR（base は main）
7. bot レビュー（codex / Copilot / CodeRabbit）を待って回収する。base が main でないと CodeRabbit は動かない
8. 指摘を実コードで検証してから採否を決める → マージ

解決値の突き合わせスクリプト

git show origin/main:src/app/sparkle-design.css > /tmp/cur.css
resolve() { v="$1"; for i in 1 2 3 4 5; do d=$(grep -m1 -- "  --color-$v:" /tmp/cur.css | sed -E 's/.*: *(.*);/\1/'); case "$d" in var\(--color-*\)) v=$(echo "$d" | sed -E 's/var\(--color-(.*)\)/\1/');; *) echo "$d"; return;; esac; done; echo "$d"; }
resolve primary-500
resolve surface-primary-high-enabled

---

3. 調査済みの Figma ノード ID（再調査不要）

fileKey 7alBZXZf65YgcII41TWT0r。色は size に依存しないので size=sm のノードだけ見ればよい。

Button（ページ ❖ Button = 233:5070 / component set 11672:4288）

variant	theme	enable	hover	active	disabled	loading
solid	primary	11672:4747	4737	4727	4717	4705
solid	neutral	11672:5239	5234	5229	5224	5218
solid	negative	11672:4752	4742	4732	4722	4711
outline	primary	11672:4591	4581	4571	4561	4549
outline	neutral	11672:5161	5156	5151	5146	5140
outline	negative	11672:4596	4586	4576	4566	4555
ghost	primary	11672:5015	4994	4984	5047	5035
ghost	neutral	11672:4435	4425	4415	4405	4393
ghost	negative	11672:4440	4430	4420	4410	4399

Icon Button（ページ ❖ Icon Button = 25:905）

variant	theme	enable	hover	active	disabled	loading
solid	primary	25:1173	25:1169	25:1165	25:1157	1057:9628
solid	neutral	1079:25729	25727	25725	25718	1079:25720
solid	negative	1079:24529	24527	24525	24518	1079:24520
outline	primary	25:1083	25:1079	25:1075	25:1067	1057:9622
outline	neutral	1079:25681	25679	25677	25670	1079:25672
outline	negative	1079:24481	24479	24477	24470	1079:24472
ghost	primary	25:993	25:989	25:985	25:977	1057:9614
ghost	neutral	1079:25631	25627	25623	25609	1079:25613
ghost	negative	1079:24431	24427	24423	24409	1079:24413

ノード ID を機械的に列挙する手順: get_metadata でページを取得 → <symbol id name="theme=…, variant=…, state=…, size=sm"> を正規表現で拾う。

---

4. Figma 未反映のためやれないもの

刷新済み Figma ファイルにページ自体が存在しない（Figma 側の更新が未マージ）。2026-08-17 に再スキャンして変化なしを確認済み（ページは 13 コンポーネント + Slot / Local Components のまま）。

Checkbox / Radio / Select / Switch / Slider / Badge / Card / Skeleton / Spinner / Dialog / Overlay / Toast / Tooltip / Tabs / Breadcrumb

search_design_system では Card / Switch がヒットするが、別ライブラリの旧版（2025-11〜2026-01 更新）なので参照してはいけない。

main に残る旧トークン数（src/components/ui/*/index.tsx、#303 マージ後）:

tabs 25 / checkbox 22 / select 15 / radio 15 / switch 12
slider 10 / card 6 / tooltip 3 / badge 2 / toast 1 / breadcrumb 1

---

5. 踏んだ落とし穴（再発しやすい）

Vercel は CSS を再生成する

vercel.json → build:registry:vercel → scripts/build-registry-vercel.sh の Step 1 で sparkle-design.css を再生成する。ここに CLI バージョンを直書きすると build:css とチャネルがずれ、Vercel だけ旧トークンで生成される。2026-08-17 に pnpm build:css 委譲へ修正済み（0c09e8a）。CSS 生成系を触ったら両方を確認すること。

#299 は「見た目が変わらない」わけではない

PR 説明に「旧トークン併存なので見た目は変わらない」とあったが誤り。プリミティブ配色 50 値とシャドウ全段が置き換わっているので、未移行コンポーネントも色・影が変わる。Figma 刷新の意図どおりではあるが、beta の見え方として認識が必要。

bot レビューは鵜呑みにしない

CodeRabbit が #302 で「Tag の outline 枠線は border/* を使うべき」と Major で指摘したが誤り。Figma は object/* を bind しており、border/* にすると枠線が激変する（neutral は L=0.449 → 0.889）。命名規則からの推論だった。必ず Figma の実バインディングと解決値で検証すること。

一方 #303 では CodeRabbit / Copilot がともに IconButton の disabled 周りを指摘し、こちらは実コードで再現を確認できた（→ #305）。正しい指摘も混ざるので、毎回コードで確かめる。

ユーティリティ名は用途名が重なる

--color-border-neutral-low → border-border-neutral-low、--color-text-neutral-high → text-text-neutral-high。気持ち悪いが正しい。

Tag の info は primary 追従をやめた

status="info" が object/info / text/info（青系固定）になった。primary を変更したテナントでも info タグは青のまま。Figma 準拠。

ローディング状態はトークンが 2 系統に分かれる

Figma のローディングノードは text/*/disabled（ラベル）と object/*/enabled（スピナー）を別々に bind している。実装ではラベルを opacity-0 で隠してスピナーだけ見せており、スピナーは text-current で親の色を継承するため、コンテナには object トークン側を当てている（#303）。

pnpm が動かないとき

pnpm test がレジストリに触って落ちる場合はバイナリ直叩きで回避:

./node_modules/.bin/vitest run --project unit
./node_modules/.bin/tsc --noEmit

pnpm lint は worktree だと親の .eslintrc.cjs を拾って落ちる（CI では起きない）。

---

6. 規約（リポジトリ CLAUDE.md の再掲・作業中に効いたもの）

• コミットは日本語・絵文字プレフィックス。amend + force-push 禁止
• PR マージは --merge（squash 禁止）。main は admin マージが要る
• 不可逆操作は hook がブロック。指示を受けてから SPARKLE_CONFIRM=1 をそのコマンドの前に付ける
• 「Figma の状態があくまで正」。Figma に無い仕様を推測で足さない。着手前に必ず再スキャンする
• Node 22.14.0 / pnpm 10.12.4 固定