Caroa UI

カラーシステム

Caroa UIのカラートークンと使い方

概要

Caroa UIは一貫したカラーシステムを提供しています。すべてのカラーはCSS変数(--caroa-color-*)として定義されており、Tailwind CSSクラスから利用できます。

カラーパレット一覧

Black(黒)

Loading...

White(白)

Loading...

Sand(サンド)

Loading...

Ash(アッシュ)

Loading...

Fog(フォグ)

Loading...

Orange(オレンジ) - ブランドカラー

Loading...

Blue(ブルー)

Loading...

Purple(パープル)

Loading...

Turquoise(ターコイズ)

Loading...

Green(グリーン)

Loading...

Red(レッド)

Loading...

Yellow(イエロー)

Loading...

セマンティックカラー

セマンティックカラーは「意味」に基づいた色の定義です。生のカラートークン(orange-baseなど)を直接使わず、セマンティックカラー(primaryなど)を使うことで、テーマ変更や一括修正が容易になります。

基本原則

// ✅ 推奨: セマンティックカラーを使う
<Button variant="primary">購入する</Button>
<div className="bg-background">...</div>
 
// ❌ 非推奨: 生のカラートークンを直接使う
<div className="bg-orange-base">...</div>

背景・テキスト系

ページ全体やコンテナの背景色に使います。

Loading...

アクション系

ボタンやインタラクティブ要素に使います。

Loading...

💡 accent と accent-action について

一般的なデザイン理論では「accent = 目立つ差し色」ですが、Caroa UIでは「温かみのある控えめな背景色」として定義しています。

accent (sand-light)

  • 静的な背景色として使用
  • ページ全体の背景、セクション背景、カードの背景など
  • 落ち着いた雰囲気を演出し、白一色より温かみのある印象を与える

accent-action (sand-base)

  • ユーザー操作に反応するインタラクティブな状態で使用
  • ホバー時、選択状態、アクティブ状態、フォーカス状態など
  • accentより少し濃い色で、操作可能であることや現在の状態を視覚的にフィードバック
// ページ背景(静的)
<main className="bg-accent">
 
// ホバー時の背景変化
<button className="hover:bg-accent-action">
 
// 選択状態の背景
<div className={cn(selected && "bg-accent-action")}>
 
// テーブル行のホバー
<tr className="hover:bg-accent-action">
 
// サイドバーのアクティブ項目
<SidebarItem className={cn(isActive && "bg-accent-action")}>

状態・フィードバック系

ユーザーへのフィードバックや状態表示に使います。

Loading...

destructive と error の使い分け

destructiveerror は同じ色(red-base)ですが、意味的に使い分けることで、コードの意図が明確になります。

// ✅ 破壊的アクション → destructive
<Button variant="destructive">削除する</Button>
<Button variant="destructive">アカウントを完全に削除</Button>
 
// ✅ エラー状態 → error
<span className="text-error">入力値が不正です</span>
<div className="border-error bg-error-light">エラーメッセージ</div>
<Input className="border-error" aria-invalid="true" />
用途使用するトークン
削除ボタンdestructive<Button variant="destructive">
取り消せない操作destructive「完全に削除」ボタン
バリデーションエラーerrortext-error, border-error
フォームエラーメッセージerror<FieldError>, text-error
エラートーストerrortoast.error()

状態色の使用例

Loading...

ボーダー・入力系

境界線やフォーム要素に使います。

Loading...

リンク・サイドバー系

Loading...

セマンティックカラー一覧(まとめ)

背景・テキスト

セマンティック実際の色Tailwindクラス用途
backgroundwhitebg-backgroundページ背景
foregroundblack-base (#1C1C1C)text-foregroundメインテキスト
sub-foregroundash-darkest (#595959)text-sub-foregrounddescription系テキスト(濃いグレー)
muted-foregroundash-dark (#A9A9A9)text-muted-foregroundplaceholder、アイコン、ショートカット表示
cardwhitebg-cardカード背景
card-foregroundblack-basetext-card-foregroundカード内テキスト
popoverwhitebg-popoverポップオーバー背景
popover-foregroundblack-basetext-popover-foregroundポップオーバー内テキスト

アクション・UI要素

セマンティック実際の色Tailwindクラス用途
primaryorange-base (#D75A11)bg-primaryブランドカラー、CTA
primary-foregroundwhitetext-primary-foregroundprimary上のテキスト
baseblack-basebg-base通常のUI(ボタンのデフォルト)
base-foregroundwhitetext-base-foregroundbase上のテキスト
secondarysand-basebg-secondaryサブ要素
secondary-foregroundblack-basetext-secondary-foregroundsecondary上のテキスト
accentsand-lightbg-accent温かみのある背景色(静的)
accent-actionsand-basebg-accent-actionホバー・選択状態の背景(インタラクティブ)
accent-foregroundblack-basetext-accent-foregroundaccent上のテキスト
mutedash-lightbg-muted無効、補足背景

状態カラー

セマンティック実際の色Tailwindクラス用途
destructivered-basebg-destructive / text-destructive破壊的アクション
destructive-foregroundwhitetext-destructive-foregrounddestructive上のテキスト
destructive-lightred-bgbg-destructive-lightエラーの薄い背景
successgreen-basebg-success / text-success成功、完了
success-foregroundwhitetext-success-foregroundsuccess上のテキスト
success-lightgreen-bgbg-success-light成功の薄い背景
warningyellow-basebg-warning / text-warning警告、注意
warning-foregroundblack-basetext-warning-foregroundwarning上のテキスト
warning-lightyellow-bgbg-warning-light警告の薄い背景
infoblue-basebg-info / text-info情報、ヒント
info-foregroundwhitetext-info-foregroundinfo上のテキスト
info-lightblue-bgbg-info-light情報の薄い背景
errorred-basetext-errorエラー(destructiveのエイリアス)

ボーダー・入力・リング

セマンティック実際の色Tailwindクラス用途
borderash-lightborder-border標準ボーダー
border-mutedash-light / 0.8border-border-muted薄めのボーダー
inputash-lightborder-input入力ボーダー
ringfog-darkring-ringフォーカスリング

リンク

セマンティック実際の色Tailwindクラス用途
linkblue-darktext-linkテキストリンク
link-foregroundwhitetext-link-foregroundlink上のテキスト(ボタン内等)

サイドバー

セマンティック実際の色Tailwindクラス用途
sidebarwhitebg-sidebarサイドバー背景
sidebar-foregroundblack-lighttext-sidebar-foregroundサイドバーテキスト
sidebar-primaryblack-basebg-sidebar-primaryサイドバーのアクティブ要素
sidebar-primary-foregroundwhitetext-sidebar-primary-foregroundsidebar-primary上のテキスト
sidebar-accentsand-lightbg-sidebar-accentサイドバーの静的ハイライト
sidebar-accent-actionsand-basebg-sidebar-accent-actionサイドバーのホバー・選択状態
sidebar-accent-foregroundblack-basetext-sidebar-accent-foregroundsidebar-accent上のテキスト
sidebar-borderash-lightborder-sidebar-borderサイドバーのボーダー
sidebar-ringblue-brightring-sidebar-ringサイドバーのフォーカスリング

テキスト色の使い分け

テキスト色は3段階で使い分けます。text-muted-foreground の乱用を避け、通常色をメインで使ってください。

用途クラス使用例
メインテキスト・機能的UItext-foregroundblack-base (#1C1C1C)見出し、ボタンラベル、ナビゲーション
description系text-sub-foregroundash-darkest (#595959)CardDescription, DialogDescription, FieldDescription
本当に補足的な要素text-muted-foregroundash-dark (#A9A9A9)placeholder, アイコン, ショートカット表示

迷ったらこれ(テキスト色の選び方)

どれを使うか迷ったら、次の3問に上から順番に答えてください。最初にYESになった時点でそのクラスに決定します。

  1. 本文・見出し・ボタンラベル・機能的UI要素か → text-foreground
  2. 説明文・サブテキスト・ラベル(タイトルとの差別化)か → text-sub-foreground
  3. placeholder・装飾アイコン・ショートカット表示など「無くても意味が通る」補足か → text-muted-foreground

①②に当てはまらないことを確認してから、最後の手段として③を選ぶ、という順序が重要です。「グレーにしたい」という見た目の理由だけで③へ飛ばないでください。

実例で確認する

// ❌ Bad - description用途なのにmutedを使っている(①②に該当するのに③を選んでいる)
<CardDescription className="text-muted-foreground">
  このカードの説明文です
</CardDescription>
 
// ✅ Good - description系はsub-foreground(Q2に該当)
<CardDescription className="text-sub-foreground">
  このカードの説明文です
</CardDescription>
// ✅ Good - placeholderは「無くても意味が通る」補足(Q3に該当)
<input placeholder="検索..." className="placeholder:text-muted-foreground" />
 
// ✅ Good - 装飾アイコンの色指定(Q3に該当)
<Icon name="Search" className="text-muted-foreground" />
 
// ✅ Good - ショートカットキー表示(Q3に該当)
<CommandShortcut className="text-muted-foreground">⌘K</CommandShortcut>
// ❌ Bad - コンボボックスの補助情報(subtitle)なのにmutedを使っている
<div className="text-xs text-muted-foreground">{option.subtitle}</div>
 
// ✅ Good - 選択肢の補助情報はdescription系としてsub-foreground(Q2に該当)
<div className="text-xs text-sub-foreground">{option.subtitle}</div>

罠: text-muted-foreground は名前に反して「補足テキスト用」ではない

名前だけを見ると「補足的なテキストには何でも使ってよい」ように読めますが、正しい適用範囲はもっと狭く、「消えても情報が失われない要素」専用です。説明文・ラベル・ステータス表示のように実際に意味のある内容へ使ってしまうと、読みにくいグレーテキストが増えるだけで、caroa-uiが目指す「静寂性」ではなく単なる可読性の低下になります。

判定に迷うときは、その要素を消してみて意味が通るかを自問してください。

  • 消しても情報が失われない(アイコンの色・placeholder・ショートカット表示など) → text-muted-foreground
  • 消すと情報が失われる(説明文・ラベル・データの一部) → text-sub-foreground または text-foreground

見え方の比較

Loading...

フォントサイズごとの見え方

Loading...
// メインテキスト
<h2 className="text-foreground">タイトル</h2>
 
// 説明文(濃いグレー)
<p className="text-sub-foreground">このカードの説明文です</p>
 
// プレースホルダー(薄いグレー)
<input placeholder="検索..." className="placeholder:text-muted-foreground" />

コンポーネントでの使い方

Buttonのカラーバリアント

Loading...
<Button>Base (Default)</Button>
<Button variant="primary">Primary</Button>
<Button variant="success">Success</Button>
<Button variant="warning">Warning</Button>
<Button variant="destructive">Destructive</Button>

Tailwind CSSでの使い方

{/* 背景色 */}
<div className="bg-orange-base">ブランドカラー背景</div>
<div className="bg-destructive-light">エラー背景(薄い)</div>
 
{/* テキスト色 */}
<p className="text-blue-base">青いテキスト</p>
<p className="text-destructive">エラーテキスト</p>
 
{/* ボーダー */}
<div className="border border-ash-base">グレーボーダー</div>
<div className="border border-destructive/20">エラーボーダー(透明度20%)</div>

CSS変数

すべてのカラートークンは--caroa-color-*形式のCSS変数として利用可能です。

/* プロジェクト固有のカスタマイズ */
:root {
  /* セマンティックカラーの上書き */
  --caroa-primary: var(--caroa-color-blue-base);
  --caroa-destructive: var(--caroa-color-red-base);
 
  /* 独自のカラー追加 */
  --brand-gradient: linear-gradient(
    to right,
    hsl(var(--caroa-color-orange-base)),
    hsl(var(--caroa-color-orange-bright))
  );
}

useAutoThemeフック

テーマカラーを動的に変更するためのフックです。

import { useAutoTheme } from '@caroainc/ui-components'
 
function App() {
  useAutoTheme({
    primary: 'blue-base',      // プライマリカラー
    base: 'black-base',        // ベースカラー
    secondary: 'sand-base',    // セカンダリカラー
    accent: 'sand-light',      // アクセントカラー
    borderRadius: '0.5rem',    // 角丸
  })
 
  return <YourApp />
}