theming-components

デザイントークンとテーマ設定システム

すべてのコンポーネントスキルの基盤となるスタイル設定アーキテクチャを提供する、包括的なデザイントークンシステムです。ブランドのカスタマイズ、テーマの切り替え、RTL サポート、一貫したビジュアルデザインを実現します。

概要

デザイントークンは、すべてのビジュアルデザインに関する決定の信頼できる唯一の情報源です。このスキルでは、次の機能を提供します。

1. 完全なトークン分類体系：7 つの主要カテゴリ（カラー、タイポグラフィ、スペーシング、ボーダー、シャドウ、モーション、z-index）
2. テーマの切り替え：ライト／ダークモード、ハイコントラスト、カスタムブランドテーマ
3. RTL／i18n サポート：CSS 論理プロパティによる、右から左に読む言語の自動サポート
4. マルチプラットフォームへのエクスポート：CSS 変数、SCSS、iOS Swift、Android XML、JavaScript
5. コンポーネントとの統合：すべてのコンポーネントで一貫したスタイルを実現するスキル連携アーキテクチャ

重要なアーキテクチャ原則：

Component Skills (Behavior + Structure) → Use tokens for ALL visual styling
Design Tokens (Styling Variables)       → Define colors, spacing, typography
Theme Files (Token Overrides)           → Light, dark, brand-specific values

---

クイックスタート

コンポーネントでトークンを使用する

ステップ 1：コンポーネント内でトークンを参照します。

.button {
  background-color: var(--button-bg-primary);
  color: var(--button-text-primary);
  padding-inline: var(--button-padding-inline);
  padding-block: var(--button-padding-block);
  border-radius: var(--button-border-radius);
  transition: var(--transition-fast);
}

ステップ 2：テーマが自動的に適用されます。

<html data-theme="light">
  <button class="button">Primary Button</button>
</html>


<html data-theme="dark">
  <button class="button">Primary Button</button>
</html>

コードを変更する必要はありません。テーマの切り替えは自動で行われます。

基本的なテーマの切り替え

function setTheme(themeName) {
  document.documentElement.setAttribute('data-theme', themeName);
  localStorage.setItem('theme', themeName);
}

function toggleTheme() {
  const current = document.documentElement.getAttribute('data-theme');
  setTheme(current === 'dark' ? 'light' : 'dark');
}

// Load saved theme on page load
setTheme(localStorage.getItem('theme') || 'light');

---

トークンの分類体系（7 つの主要カテゴリ）

1. カラートークン

3 層の階層：プリミティブ → セマンティック → コンポーネント

/* Primitive (9-shade scales) */
--color-blue-500: #3B82F6;

/* Semantic (purpose-based) */
--color-primary: var(--color-blue-500);
--color-success: var(--color-green-500);
--color-error: var(--color-red-500);

/* Component-specific */
--button-bg-primary: var(--color-primary);

カラーシステムの全容： references/color-system.md を参照してください。

2. スペーシングトークン

4px を基準とするスケール：

--space-1: 4px;   --space-2: 8px;   --space-4: 16px;
--space-6: 24px;  --space-8: 32px;  --space-12: 48px;

/* Semantic */
--spacing-sm: var(--space-2);   /* 8px */
--spacing-md: var(--space-4);   /* 16px */
--spacing-lg: var(--space-6);   /* 24px */

3. タイポグラフィトークン

--font-sans: 'Inter', -apple-system, sans-serif;
--font-mono: 'Fira Code', monospace;

--font-size-sm: 14px;
--font-size-base: 16px;
--font-size-lg: 18px;

--font-weight-normal: 400;
--font-weight-semibold: 600;
--font-weight-bold: 700;

4. ボーダーと角丸のトークン

--border-width-thin: 1px;
--border-width-medium: 2px;

--radius-sm: 4px;
--radius-md: 8px;
--radius-lg: 12px;
--radius-full: 9999px;

5. シャドウトークン

--shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.07);
--shadow-md: 0 4px 8px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 8px 16px rgba(0, 0, 0, 0.12);

--shadow-focus-primary: 0 0 0 3px rgba(59, 130, 246, 0.3);

6. モーショントークン

--duration-fast: 150ms;
--duration-normal: 200ms;

--ease-out: cubic-bezier(0, 0, 0.2, 1);
--transition-fast: all var(--duration-fast) var(--ease-out);

モーション低減のサポート：

@media (prefers-reduced-motion: reduce) {
  :root { --transition-fast: none; }
}

7. Z-index トークン

--z-dropdown: 1000;
--z-modal-backdrop: 1040;
--z-modal: 1050;
--z-tooltip: 1070;

---

テーマアーキテクチャ

ライト／ダークテーマ

/* themes/light.css */
:root {
  --color-primary: #3B82F6;
  --color-background: #FFFFFF;
  --color-text-primary: #1F2937;
}

/* themes/dark.css */
:root[data-theme="dark"] {
  --color-primary: #60A5FA;
  --color-background: #111827;
  --color-text-primary: #F9FAFB;
}

カスタムブランドテーマ

:root[data-theme="my-brand"] {
  --color-primary: #FF6B35;
  --font-sans: 'Poppins', sans-serif;
  --radius-md: 12px;
}

テーマガイドの全容： references/theme-switching.md を参照してください。

---

CSS 論理プロパティ（RTL サポート）

RTL 言語を自動でサポートするには、論理プロパティを使用します。

物理プロパティ（使用を避ける）	論理プロパティ（使用する）
margin-left	margin-inline-start
padding-right	padding-inline-end
text-align: left	text-align: start

/* Correct - auto-flips in RTL */
.button {
  padding-inline: var(--button-padding-inline);
  margin-inline-start: var(--spacing-sm);
}

RTL ガイドの全容： references/logical-properties.md を参照してください。

---

コンポーネントとの統合

すべてのコンポーネントスキルで、次の命名規則を使用します。

--{component}-{property}-{variant?}-{state?}

例：

--button-bg-primary
--button-bg-primary-hover
--input-border-color-focus
--chart-color-1

コンポーネントでは、すべてのスタイル設定にトークンを使用します。

.button {
  background-color: var(--button-bg-primary);
  border-radius: var(--button-border-radius);
}

テーマを変更すると、すべてのコンポーネントが自動的に更新されます。

統合ガイドの全容： references/component-integration.md を参照してください。

---

アクセシビリティ

WCAG 2.1 AA 準拠

• 通常のテキスト：コントラスト比 4.5:1 以上
• 大きなテキスト（18px 以上）：3:1 以上
• UI コンポーネント：3:1 以上

ハイコントラストテーマ

:root[data-theme="high-contrast"] {
  --color-primary: #0000FF;
  --color-text-primary: #000000;
  /* 7:1 contrast (WCAG AAA) */
}

モーション低減

@media (prefers-reduced-motion: reduce) {
  :root {
    --duration-fast: 0ms;
    --transition-fast: none;
  }
}

アクセシビリティガイドの全容： references/accessibility-tokens.md を参照してください。

---

プラットフォームへのエクスポート（Style Dictionary）

トークンを任意のプラットフォーム向けに変換します。

JSON Tokens → Style Dictionary → CSS Variables
                               → iOS Swift
                               → Android XML
                               → JavaScript

npm run build-tokens

セットアップガイドの全容： references/style-dictionary-setup.md を参照してください。

---

W3C トークン形式

{
  "color": {
    "primary": {
      "$value": "#3B82F6",
      "$type": "color"
    }
  }
}

---

スクリプト

# Generate color scale from base color
python scripts/generate_color_scale.py --base "#3B82F6"

# Validate token structure
python scripts/validate_tokens.py

# Check WCAG contrast ratios
python scripts/validate_contrast.py

# Build all platforms
npm run build-tokens

---

参考資料

コアシステム：

• references/color-system.md - カラースケールとセマンティクスの全容
• references/typography-system.md - 文字スケールとフォント
• references/spacing-system.md - スペーシングスケールとリズム

実装：

• references/theme-switching.md - ライト／ダークモード、カスタムテーマ
• references/component-integration.md - スキルでのトークンの使用方法
• references/logical-properties.md - RTL サポートのパターン

ツールとアクセシビリティ：

• references/style-dictionary-setup.md - マルチプラットフォームビルド
• references/accessibility-tokens.md - WCAG 準拠

---

主なポイント

1. デザイントークンが基盤です - すべてのビジュアルスタイルはトークンに基づいています
2. 3段階の階層構造 - プリミティブ → セマンティック → コンポーネントのトークン
3. 7つの主要カテゴリ - 色、間隔、タイポグラフィ、境界線、影、モーション、z-index
4. テーマ切り替えを標準搭載 - ライト、ダーク、ハイコントラスト、カスタムブランド
5. RTLを自動サポート - CSS論理プロパティにより、右から左に記述する言語に対応します
6. アクセシビリティを最優先 - WCAG準拠、モーションの低減、ハイコントラスト
7. すべてのスキルで参照 - すべてのコンポーネントスキルでデザイントークンを使用します

---

段階的な情報開示： このSKILL.mdでは概要とクイックスタートを説明します。詳細なドキュメントはreferences/ディレクトリにあります。

スキル連携のアーキテクチャ： SKILL_CHAINING_ARCHITECTURE.mdを参照してください