コンテンツにスキップ

ストアフロント UI スタイルガイド

目的

本ドキュメントは、Tailwind CSS v4 と shadcn/ui を使用した BtoB ストアフロントのデザインシステムを定義します。セマンティックトークンを使用することで、一貫性のあるデザインと保守性の高いコードを実現します。

🎨 カラーシステム（shadcn/ui 標準）

セマンティックカラートークン

トークン 用途 使用例
background ページ全体の背景色 bg-background
foreground メインテキスト色 text-foreground
card カード・パネルの背景 bg-card
card-foreground カード内のテキスト text-card-foreground
primary プライマリアクション bg-primary, text-primary
primary-foreground プライマリ要素上のテキスト text-primary-foreground
muted 控えめな背景 bg-muted
muted-foreground 補助テキスト text-muted-foreground
border ボーダー色 border, border-border
input 入力フィールドの背景 bg-input
ring フォーカスリング ring, ring-ring
destructive エラー・削除アクション text-destructive, bg-destructive

⚠️ 禁止事項

以下のハードコードされた色指定は使用禁止です：

❌ 禁止例
className="bg-white"           // → bg-card
className="text-neutral-400"   // → text-foreground
className="text-neutral-300"   // → text-muted-foreground
className="border-neutral-100" // → border
className="bg-primary-500"     // → bg-primary
className="text-blue-600"      // → text-primary

✅ 推奨例
className="bg-card"
className="text-foreground"
className="text-muted-foreground"
className="border"
className="bg-primary"
className="text-primary"

透明度の使用

特定の不透明度が必要な場合は、/ 記法を使用します：

className = 'bg-primary/10'; // 10% 不透明度
className = 'border-primary/20'; // 20% 不透明度
className = 'bg-card/90'; // 90% 不透明度

📐 スペーシング・サイズ

正方形要素の簡潔表記

❌ 禁止例
className="h-4 w-4"   // → size-4
className="h-6 w-6"   // → size-6

✅ 推奨例
className="size-4"
className="size-6"
className="size-full"

ボーダー指定

❌ 禁止例
className="border border-neutral-100"  // 冗長

✅ 推奨例
className="border"                     // borderだけでOK
className="border-b"                   // 下部ボーダーのみ
className="border-t"                   // 上部ボーダーのみ

🎯 タイポグラフィ

フォントスタック

用途 設定
ベース本文 Noto Sans JP, Roboto, Hiragino Sans, Meiryo, sans-serif
見出し Sawarabi Mincho, EB Garamond, Noto Sans JP, Yu Mincho, serif

テキストカラー使用例

// メインテキスト
<h1 className="text-foreground">見出し</h1>

// 補助テキスト
<p className="text-muted-foreground">説明文</p>

// プライマリテキスト
<span className="text-primary">強調</span>

// エラーテキスト
<p className="text-destructive">エラーメッセージ</p>

🧩 コンポーネント設計指針

ボタン

// プライマリボタン
<Button className="bg-primary text-primary-foreground">
  購入する
</Button>

// セカンダリボタン
<Button variant="outline">
  詳細を見る
</Button>

// ゴーストボタン
<Button variant="ghost">
  キャンセル
</Button>

カード

<div className="rounded-lg border bg-card p-6 shadow-sm">
  <h3 className="text-foreground">カードタイトル</h3>
  <p className="text-muted-foreground">カードの説明文</p>
</div>

フォーム

<div className="space-y-2">
  <label className="text-sm font-medium text-foreground">ラベル</label>
  <Input className="border bg-input" />
  <p className="text-xs text-muted-foreground">ヘルプテキスト</p>
</div>

📋 CSS変数の定義（globals.css）

必須構造

:root {
  /* HSL値で定義 */
  --background: hsl(0 0% 100%);
  --foreground: hsl(240 10% 3.9%);
  --card: hsl(0 0% 100%);
  --card-foreground: hsl(240 10% 3.9%);
  --primary: hsl(240 5.9% 10%);
  --primary-foreground: hsl(0 0% 98%);
  --muted: hsl(240 4.8% 95.9%);
  --muted-foreground: hsl(240 3.8% 46.1%);
  --border: hsl(240 5.9% 90%);
  --input: hsl(240 5.9% 90%);
  --ring: hsl(240 5.9% 10%);
  --destructive: hsl(0 84.2% 60.2%);
  --destructive-foreground: hsl(0 0% 98%);
  --radius: 0.75rem;
}

.dark {
  /* ダークモード用の定義 */
  --background: hsl(240 10% 3.9%);
  --foreground: hsl(0 0% 98%);
  /* ... */
}

@theme inline {
  /* var(--*)をそのまま使用（hsl()でラップしない） */
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-border: var(--border);
  --color-primary: var(--primary);
  /* ... */

  /* 角丸のバリエーション */
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}

@layer base {
  * {
    /* @applyディレクティブを使用 */
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground;
  }
}

🚫 アンチパターン

1. ハードコードされた色

❌ 避けるべき
<div className="bg-white text-neutral-400 border-neutral-100">
<span className="text-primary-500">
<p className="text-red-600">エラー</p>

2. 重複した指定

❌ 避けるべき
<div className="border border-neutral-100">  // border-neutral-100は不要
<div className="h-4 w-4">                    // size-4を使用

3. CSS変数の誤った記法

❌ 避けるべき :root {
  --background: 0 0% 100%; /* hsl()でラップしていない */
}
@theme inline {
  --color-background: hsl(var(--background)); /* hsl()でラップしている */
}

✅ チェックリスト

コンポーネント実装時の確認事項：

  • ハードコードされた色（neutral-*, primary-*, white等）を使用していない
  • セマンティックトークン（foreground, muted-foreground, primary等）を使用している
  • 正方形要素に size-* を使用している
  • border の冗長な指定を避けている
  • 透明度が必要な場合は / 記法を使用している
  • globals.css の CSS変数は標準形式に準拠している

🔗 参考資料