カラーシステム
Caroa UIのカラートークンと使い方
概要
Caroa UIは一貫したカラーシステムを提供しています。すべてのカラーはCSS変数(--caroa-color-*)として定義されており、Tailwind CSSクラスから利用できます。
カラーパレット一覧
Black(黒)
White(白)
Sand(サンド)
Ash(アッシュ)
Fog(フォグ)
Orange(オレンジ) - ブランドカラー
Blue(ブルー)
Purple(パープル)
Turquoise(ターコイズ)
Green(グリーン)
Red(レッド)
Yellow(イエロー)
セマンティックカラー
セマンティックカラーは「意味」に基づいた色の定義です。生のカラートークン(orange-baseなど)を直接使わず、セマンティックカラー(primaryなど)を使うことで、テーマ変更や一括修正が容易になります。
基本原則
背景・テキスト系
ページ全体やコンテナの背景色に使います。
アクション系
ボタンやインタラクティブ要素に使います。
💡 accent と accent-action について
一般的なデザイン理論では「accent = 目立つ差し色」ですが、Caroa UIでは「温かみのある控えめな背景色」として定義しています。
accent (sand-light)
- 静的な背景色として使用
- ページ全体の背景、セクション背景、カードの背景など
- 落ち着いた雰囲気を演出し、白一色より温かみのある印象を与える
accent-action (sand-base)
- ユーザー操作に反応するインタラクティブな状態で使用
- ホバー時、選択状態、アクティブ状態、フォーカス状態など
- accentより少し濃い色で、操作可能であることや現在の状態を視覚的にフィードバック
状態・フィードバック系
ユーザーへのフィードバックや状態表示に使います。
destructive と error の使い分け
destructive と error は同じ色(red-base)ですが、意味的に使い分けることで、コードの意図が明確になります。
| 用途 | 使用するトークン | 例 |
|---|---|---|
| 削除ボタン | destructive | <Button variant="destructive"> |
| 取り消せない操作 | destructive | 「完全に削除」ボタン |
| バリデーションエラー | error | text-error, border-error |
| フォームエラーメッセージ | error | <FieldError>, text-error |
| エラートースト | error | toast.error() |
状態色の使用例
ボーダー・入力系
境界線やフォーム要素に使います。
リンク・サイドバー系
セマンティックカラー一覧(まとめ)
背景・テキスト
| セマンティック | 実際の色 | Tailwindクラス | 用途 |
|---|---|---|---|
background | white | bg-background | ページ背景 |
foreground | black-base (#1C1C1C) | text-foreground | メインテキスト |
sub-foreground | ash-darkest (#595959) | text-sub-foreground | description系テキスト(濃いグレー) |
muted-foreground | ash-dark (#A9A9A9) | text-muted-foreground | placeholder、アイコン、ショートカット表示 |
card | white | bg-card | カード背景 |
card-foreground | black-base | text-card-foreground | カード内テキスト |
popover | white | bg-popover | ポップオーバー背景 |
popover-foreground | black-base | text-popover-foreground | ポップオーバー内テキスト |
アクション・UI要素
| セマンティック | 実際の色 | Tailwindクラス | 用途 |
|---|---|---|---|
primary | orange-base (#D75A11) | bg-primary | ブランドカラー、CTA |
primary-foreground | white | text-primary-foreground | primary上のテキスト |
base | black-base | bg-base | 通常のUI(ボタンのデフォルト) |
base-foreground | white | text-base-foreground | base上のテキスト |
secondary | sand-base | bg-secondary | サブ要素 |
secondary-foreground | black-base | text-secondary-foreground | secondary上のテキスト |
accent | sand-light | bg-accent | 温かみのある背景色(静的) |
accent-action | sand-base | bg-accent-action | ホバー・選択状態の背景(インタラクティブ) |
accent-foreground | black-base | text-accent-foreground | accent上のテキスト |
muted | ash-light | bg-muted | 無効、補足背景 |
状態カラー
| セマンティック | 実際の色 | Tailwindクラス | 用途 |
|---|---|---|---|
destructive | red-base | bg-destructive / text-destructive | 破壊的アクション |
destructive-foreground | white | text-destructive-foreground | destructive上のテキスト |
destructive-light | red-bg | bg-destructive-light | エラーの薄い背景 |
success | green-base | bg-success / text-success | 成功、完了 |
success-foreground | white | text-success-foreground | success上のテキスト |
success-light | green-bg | bg-success-light | 成功の薄い背景 |
warning | yellow-base | bg-warning / text-warning | 警告、注意 |
warning-foreground | black-base | text-warning-foreground | warning上のテキスト |
warning-light | yellow-bg | bg-warning-light | 警告の薄い背景 |
info | blue-base | bg-info / text-info | 情報、ヒント |
info-foreground | white | text-info-foreground | info上のテキスト |
info-light | blue-bg | bg-info-light | 情報の薄い背景 |
error | red-base | text-error | エラー(destructiveのエイリアス) |
ボーダー・入力・リング
| セマンティック | 実際の色 | Tailwindクラス | 用途 |
|---|---|---|---|
border | ash-light | border-border | 標準ボーダー |
border-muted | ash-light / 0.8 | border-border-muted | 薄めのボーダー |
input | ash-light | border-input | 入力ボーダー |
ring | fog-dark | ring-ring | フォーカスリング |
リンク
| セマンティック | 実際の色 | Tailwindクラス | 用途 |
|---|---|---|---|
link | blue-dark | text-link | テキストリンク |
link-foreground | white | text-link-foreground | link上のテキスト(ボタン内等) |
サイドバー
| セマンティック | 実際の色 | Tailwindクラス | 用途 |
|---|---|---|---|
sidebar | white | bg-sidebar | サイドバー背景 |
sidebar-foreground | black-light | text-sidebar-foreground | サイドバーテキスト |
sidebar-primary | black-base | bg-sidebar-primary | サイドバーのアクティブ要素 |
sidebar-primary-foreground | white | text-sidebar-primary-foreground | sidebar-primary上のテキスト |
sidebar-accent | sand-light | bg-sidebar-accent | サイドバーの静的ハイライト |
sidebar-accent-action | sand-base | bg-sidebar-accent-action | サイドバーのホバー・選択状態 |
sidebar-accent-foreground | black-base | text-sidebar-accent-foreground | sidebar-accent上のテキスト |
sidebar-border | ash-light | border-sidebar-border | サイドバーのボーダー |
sidebar-ring | blue-bright | ring-sidebar-ring | サイドバーのフォーカスリング |
テキスト色の使い分け
テキスト色は3段階で使い分けます。text-muted-foreground の乱用を避け、通常色をメインで使ってください。
| 用途 | クラス | 色 | 使用例 |
|---|---|---|---|
| メインテキスト・機能的UI | text-foreground | black-base (#1C1C1C) | 見出し、ボタンラベル、ナビゲーション |
| description系 | text-sub-foreground | ash-darkest (#595959) | CardDescription, DialogDescription, FieldDescription |
| 本当に補足的な要素 | text-muted-foreground | ash-dark (#A9A9A9) | placeholder, アイコン, ショートカット表示 |
迷ったらこれ(テキスト色の選び方)
どれを使うか迷ったら、次の3問に上から順番に答えてください。最初にYESになった時点でそのクラスに決定します。
- 本文・見出し・ボタンラベル・機能的UI要素か →
text-foreground - 説明文・サブテキスト・ラベル(タイトルとの差別化)か →
text-sub-foreground - placeholder・装飾アイコン・ショートカット表示など「無くても意味が通る」補足か →
text-muted-foreground
①②に当てはまらないことを確認してから、最後の手段として③を選ぶ、という順序が重要です。「グレーにしたい」という見た目の理由だけで③へ飛ばないでください。
実例で確認する
罠: text-muted-foreground は名前に反して「補足テキスト用」ではない
名前だけを見ると「補足的なテキストには何でも使ってよい」ように読めますが、正しい適用範囲はもっと狭く、「消えても情報が失われない要素」専用です。説明文・ラベル・ステータス表示のように実際に意味のある内容へ使ってしまうと、読みにくいグレーテキストが増えるだけで、caroa-uiが目指す「静寂性」ではなく単なる可読性の低下になります。
判定に迷うときは、その要素を消してみて意味が通るかを自問してください。
- 消しても情報が失われない(アイコンの色・placeholder・ショートカット表示など) →
text-muted-foreground - 消すと情報が失われる(説明文・ラベル・データの一部) →
text-sub-foregroundまたはtext-foreground
見え方の比較
フォントサイズごとの見え方
コンポーネントでの使い方
Buttonのカラーバリアント
Tailwind CSSでの使い方
CSS変数
すべてのカラートークンは--caroa-color-*形式のCSS変数として利用可能です。
useAutoThemeフック
テーマカラーを動的に変更するためのフックです。