カラークラス名の移行ガイド
このガイドの対象: 2026年4月28日のリリースより前のバージョンを使っているプロジェクト向けです。4月28日以降のリリースでは新しいカラー命名が標準となっているため、新規導入の場合はセットアップの手順をそのまま参照してください。
Rabee UI のカラー定義は、短く直感的な名前に刷新されました。既存プロジェクトでは、以下のいずれかの方針で移行できます。
- 方法1: Claude Code で置き換える(推奨) ... AIに文脈を踏まえて旧クラス名を新クラス名に置換させる
- 方法2: sed コマンドで一括置換する ... 機械的に文字列置換を行う
- 方法3: 新旧併用(段階的移行) ... 互換用の CSS を追加し、旧クラス名も引き続き動作させる
置き換えの対象
以下はすべて旧命名のサフィックスを含むため、置き換え対象です。方法1・方法2 のマッピングはこれらすべてを同じルール(サフィックスの変更)でカバーします。
- Tailwind ユーティリティクラス ...
bg-*、text-*、border-*、divide-*、outline-*、ring-*、from-*、to-*など @applyディレクティブ内の記述 ...@apply bg-base-container-default;など- CSS 変数の参照 ...
color: var(--color-base-foreground-default);など - CSS 変数の独自定義・上書き ...
@theme { --color-base-container-default: ...; }など
方法1: Claude Code で置き換える(推奨)
Claude Code を使うと、border-input と border-border の使い分けのように文脈に応じた判断が必要な箇所も処理できます。プロジェクトのルートで Claude Code を起動し、以下のプロンプトを貼り付けて実行してください。
Rabee UI のカラークラス名を新しい命名に置き換えてください。
## 参考資料(作業前に WebFetch で必ず読み込んでください)
- カラーの名前と用途: https://rabeeui.com/docs/colors
- 本移行ガイド全体: https://rabeeui.com/docs/migration/colors
## 対象
`src/` 配下のすべての `.svelte` / `.ts` / `.tsx` / `.css` / `.js` / `.jsx` / `.html` ファイル。
以下の**すべて**が対象です(サフィックスが共通なので下記マッピングで一括対応できます)。
- Tailwind ユーティリティクラス(`bg-base-container-default` など)
- `@apply` ディレクティブ(`@apply bg-base-container-default;` など)
- CSS 変数の参照(`var(--color-base-container-default)` など)
- CSS 変数の独自定義・上書き(`--color-base-container-default: ...;` など)
## 置換マッピング
### Surface
- `base-container-default` → `surface`
- `base-surface-default` → `surface`
- `base-container-primary` → `inverse`
- `base-container-muted` → `muted`
- `base-container-subarea-accent` → `subarea-accent`
- `base-container-accent` → `accent`
- `base-surface-subarea-default` → `subarea`
- `base-surface-muted` → `subtle`
### Foreground
- `base-foreground-on-fill-inverse` → `inverse-foreground`
- `base-foreground-on-fill-bright` → `bright-foreground`
- `base-foreground-subarea-default` → `subarea-foreground`
- `base-foreground-subarea-accent` → `subarea-accent-foreground`
- `base-foreground-default` → `foreground`
- `base-foreground-accent` → `accent-foreground`
- `base-foreground-muted` → `muted-foreground`
- `base-foreground-subtle` → `subtle-foreground`
- `base-foreground-link` → `link`
### Border
- `base-stroke-default` → 下記「注意事項」参照
### Function
- `destructive-on-fill` → `destructive-foreground`
- `warning-on-fill` → `warning-foreground`
- `success-on-fill` → `success-foreground`
- `primary-on-fill` → `primary-foreground`
### Overlay
- `alpha-bright` → `overlay-bright`
- `alpha-gloom` → `overlay-dark`
## 注意事項
1. **`base-stroke-default` の置き換え**: フォーム入力要素(Checkbox、Radio、Input、Textarea、Select など)の内部で使われている場合は `border-input` / `divide-input` に、Card / CheckboxCard / RadioCard などフォーム**以外**では `border-border` / `divide-border` に置き換えてください。文脈を読んで判断してください。
2. **`ring-primary` / `outline-primary` の扱い**: 旧コードがフォーカスリングを `primary` カラーで描画していた箇所は、専用トークン `ring-ring` / `outline-ring` に置き換えてください。ただし装飾用途(ボタンのアクセントリングなど)で意図的に `primary` カラーを使っている場合はそのまま維持してください。
3. **作業後**: 置き換えた箇所を一覧で報告し、特に `border-input` / `border-border` の使い分けと `ring-primary` / `outline-primary` の判断根拠を示してください。
Claude Code から置換結果の報告が出たら、レビューしてからマージすることをおすすめします。
方法2: sed コマンドで一括置換する
機械的に文字列置換だけしたい場合は sed が使えます。この方法では base-stroke-default はすべて border に置換されるので、フォーム要素の箇所は置換後に手動で border-input / divide-input へ修正してください。
find src -type f \( -name "*.svelte" -o -name "*.ts" -o -name "*.css" \) \
-exec sed -i '' \
-e 's/base-container-default/surface/g' \
-e 's/base-container-primary/inverse/g' \
-e 's/base-container-muted/muted/g' \
-e 's/base-container-subarea-accent/subarea-accent/g' \
-e 's/base-container-accent/accent/g' \
-e 's/base-surface-default/surface/g' \
-e 's/base-surface-subarea-default/subarea/g' \
-e 's/base-surface-muted/subtle/g' \
-e 's/base-foreground-on-fill-inverse/inverse-foreground/g' \
-e 's/base-foreground-on-fill-bright/bright-foreground/g' \
-e 's/base-foreground-subarea-default/subarea-foreground/g' \
-e 's/base-foreground-subarea-accent/subarea-accent-foreground/g' \
-e 's/base-foreground-default/foreground/g' \
-e 's/base-foreground-accent/accent-foreground/g' \
-e 's/base-foreground-muted/muted-foreground/g' \
-e 's/base-foreground-subtle/subtle-foreground/g' \
-e 's/base-foreground-link/link/g' \
-e 's/base-stroke-default/border/g' \
-e 's/destructive-on-fill/destructive-foreground/g' \
-e 's/warning-on-fill/warning-foreground/g' \
-e 's/success-on-fill/success-foreground/g' \
-e 's/primary-on-fill/primary-foreground/g' \
-e 's/alpha-bright/overlay-bright/g' \
-e 's/alpha-gloom/overlay-dark/g' \
{} +
注意: 置換漏れが起きやすいケース
sed は単純な文字列置換なので、以下のようなケースは拾いきれません。方法1(Claude Code)と比べると漏れが発生しやすいため、置換後の検証が必須です。
- 対象拡張子の不足 ... 上記コマンドは
.svelte/.ts/.cssのみを対象としています。プロジェクトで.tsx/.jsx/.js/.html/.vue/.scss/.pcss/.lessなどを使っている場合はfindの-nameに追加してください(raw CSS のvar(--color-*)参照も対象に含めるため) - プラットフォーム依存 ...
sed -i ''は macOS 向けの書き方です。Linux ではsed -i(空文字の引数なし)に書き換える必要があります - 動的に組み立てたクラス名 ...
`text-${variant}-foreground-default`、cvaのバリアントで分割された文字列、テンプレート文字列連結などは置換されません - 順序は長いサフィックスから先に ... 短いパターンが長いパターンの一部になると先行マッチで壊れるため、長い方を先に置換します(上記コマンドもこの順序で並べてあります)
base-stroke-defaultは一律でborderに置換される ... フォーム要素(Checkbox / Radio / Input / Textarea / Select など)の内部ボーダーは手動でborder-input/divide-inputに直してください- 外部ドキュメントやビルド成果物 ...
README.md/CHANGELOG.mdやdist/配下のコード例・スクリーンショットなどは含まれていません
置換後の確認
以下のコマンドで旧クラス名の残存をチェックすることをおすすめします。
grep -rnE 'base-(container|surface|foreground|stroke)|-on-fill|alpha-(bright|gloom)' src/
ヒットした箇所は手動で修正するか、方法1(Claude Code)に切り替えて文脈判断を任せるのが安全です。また、各画面を目視で確認し、色が崩れていないかレビューすることをおすすめします。
方法3: 新旧併用(段階的移行)
一気に置き換えることが難しい場合、旧クラス名を新 CSS 変数へのエイリアスとして定義する互換 CSS を追加する方法があります。互換 CSS を読み込んでいる間は、旧クラス名と新クラス名の両方が動作します。
手順
- プロジェクトの CSS ディレクトリに以下の内容で
colors-compat.cssを配置する app.cssで Rabee UI の新カラー定義(rabeeui.css)を読み込んだ後に@importする
@import 'tailwindcss';
@import './rabeeui.css';
@import './colors-compat.css';
`colors-compat.css` の中身
@theme {
/* container(旧) → surface 系(新) */
--color-base-container-default: var(--color-surface);
--color-base-container-primary: var(--color-inverse);
--color-base-container-muted: var(--color-muted);
--color-base-container-accent: var(--color-accent);
--color-base-container-subarea-accent: var(--color-subarea-accent);
/* surface(旧) → surface 系(新) */
--color-base-surface-default: var(--color-surface);
--color-base-surface-subarea-default: var(--color-subarea);
--color-base-surface-muted: var(--color-subtle);
/* foreground(旧) → foreground 系(新) */
--color-base-foreground-default: var(--color-foreground);
--color-base-foreground-accent: var(--color-accent-foreground);
--color-base-foreground-muted: var(--color-muted-foreground);
--color-base-foreground-subtle: var(--color-subtle-foreground);
--color-base-foreground-on-fill-inverse: var(--color-inverse-foreground);
--color-base-foreground-on-fill-bright: var(--color-bright-foreground);
--color-base-foreground-subarea-default: var(--color-subarea-foreground);
--color-base-foreground-subarea-accent: var(--color-subarea-accent-foreground);
--color-base-foreground-link: var(--color-link);
/* stroke(旧) → border(新) */
--color-base-stroke-default: var(--color-border);
/* function on-fill(旧) → *-foreground(新) */
--color-destructive-on-fill: var(--color-destructive-foreground);
--color-warning-on-fill: var(--color-warning-foreground);
--color-success-on-fill: var(--color-success-foreground);
--color-primary-on-fill: var(--color-primary-foreground);
/* alpha(旧) → overlay(新) */
--color-alpha-bright: var(--color-overlay-bright);
--color-alpha-gloom: var(--color-overlay-dark);
}
本ファイルを読み込むと、旧変数が新変数のエイリアスとなり、Tailwind が旧クラス名に対応するユーティリティクラスを自動生成します。ダークモードの切り替えも新変数経由で追従するため、個別に対応する必要はありません。
注意: 互換レイヤーは恒久的に使うものではなく、移行期間中の一時的な措置です。最終的には方法1または方法2で完全置き換えを行い、互換 CSS を削除することをおすすめします。
クラス名の対応表
下表は Tailwind ユーティリティクラスの例で示していますが、CSS 変数を直接参照している箇所 も同じサフィックスの変更で置き換わります(例: --color-base-container-default → --color-surface、var(--color-base-foreground-muted) → var(--color-muted-foreground))。
Surface(背景)
| 旧クラス名 | 新クラス名 |
|---|---|
bg-base-container-default / bg-base-surface-default |
bg-surface |
bg-base-container-primary |
bg-inverse |
bg-base-container-muted |
bg-muted |
bg-base-container-accent |
bg-accent |
bg-base-container-subarea-accent |
bg-subarea-accent |
bg-base-surface-subarea-default |
bg-subarea |
bg-base-surface-muted |
bg-subtle |
Foreground(前景)
| 旧クラス名 | 新クラス名 |
|---|---|
text-base-foreground-default |
text-foreground |
text-base-foreground-accent |
text-accent-foreground |
text-base-foreground-muted |
text-muted-foreground |
text-base-foreground-subtle |
text-subtle-foreground |
text-base-foreground-on-fill-inverse |
text-inverse-foreground |
text-base-foreground-on-fill-bright |
text-bright-foreground |
text-base-foreground-subarea-default |
text-subarea-foreground |
text-base-foreground-subarea-accent |
text-subarea-accent-foreground |
text-base-foreground-link |
text-link |
Border(ボーダー)
| 旧クラス名 | 新クラス名 |
|---|---|
border-base-stroke-default / divide-base-stroke-default |
border-border / divide-border(または border-input ※) |
※ フォーム要素(Input、Textarea、Select、Checkbox、Radio 等)のボーダーは border-input を使います。詳細は後述の「注意事項」を参照してください。
Function(機能カラー)
| 旧クラス名 | 新クラス名 |
|---|---|
bg-destructive-on-fill / text-destructive-on-fill |
bg-destructive-foreground / text-destructive-foreground |
bg-warning-on-fill / text-warning-on-fill |
bg-warning-foreground / text-warning-foreground |
bg-success-on-fill / text-success-on-fill |
bg-success-foreground / text-success-foreground |
bg-primary-on-fill / text-primary-on-fill |
bg-primary-foreground / text-primary-foreground |
Overlay(オーバーレイ)
| 旧クラス名 | 新クラス名 |
|---|---|
bg-alpha-bright |
bg-overlay-bright |
bg-alpha-gloom |
bg-overlay-dark |
注意事項
`warning-foreground` の値変更
--color-warning-on-fill (旧: #18181B) は --color-warning-foreground (新: #451A03) に置き換わり、値自体も変更されました。コントラストを改善するための修正です。方法3の互換 CSS を使用する場合も、新しい値(#451A03)が適用されます。
`border-input` と `border-border` の使い分け
フォーム要素専用のボーダー色として border-input が追加されました。現在 --color-border と --color-input は同じ値ですが、将来的に分離する余地を残すため使い分けることをおすすめします。
border-input... Checkbox、Radio、Input、Textarea、Select など、フォーム内部の要素border-border... Card、Checkbox Card、Radio Card など、フォーム以外または複合的な要素
旧 border-base-stroke-default を置き換える際は、対象要素がフォーム入力要素かどうかを確認することをおすすめします。
`ring` / `outline`(フォーカスリング・グロー)について
フォーカス時のリング色として --color-ring が新規追加されました。旧コードが primary をフォーカスリングに流用していた場合、以下のように色トークンの置き換えが必要です。
| 旧 | 新 |
|---|---|
ring-primary |
ring-ring |
outline-primary |
outline-ring |
これに加えて、Rabee UI 内では用途ごとに ring-* と outline-* を以下のように使い分けています。移行時は色トークンの rename だけでなく、この慣習も参考にすると揃えやすくなります。
- 一般的なフォーカスリング →
outline-ring outline-offset-2 focus-visible:outline-2(Button、Input、Select、Menu 等の多くのコンポーネントで採用) - hover 時の薄いグロー →
hover:ring-4 hover:ring-ring/20(Checkbox、Radio、Switch 等) - inset ring や thumb の focus 表示 →
ring-*(Slider、Notification 等で引き続き利用)
ring-primary/20(旧ロジックの hover グロー)を使っていた場合は、ring-ring/20 に置き換えてください。
お困りの際は、お問い合わせフォームまたは Discord からお気軽にご相談ください。