Tailwind v3 + v4

Tailwind CSS v3 / v4 デュアルサポートの仕組み。
コンポーネントコードは単一ソースを維持し、テーマファイルでバージョン差分を吸収します。
セットアップ方法はInstallationページを参照してください。

デュアルサポート

単一ソース

2 テーマファイル

Architecture

figma-tokens.json → variables.css が唯一の値ソース。v3-preset.js と v4-theme.css は variables.css を参照するマッピングレイヤーです。

Sync Flow

figma-tokens.json

Single Source of Truth

sync-tokens

生成ファイル

variables.css

全トークンの HEX 値

light.css

:root

dark.css

.dark

v3-preset.js

JS config + plugins

v4-theme.css

@theme + @utility

ユーティリティ提供

コンポーネント（共通コード）

bg-primary, text-md, rounded-md ...

v3 の仕組み

JS プリセット（theme.extend）
CSS変数を var() で参照
plugins でカスタムユーティリティ定義
セマンティックカラーの bg-primary/50 対応（RGB チャンネル変数）

v4 の仕組み

CSS @theme + @utility
var() 参照 + HEX フォールバック（同名変数はカスケードで上書き）
color-mix() でランタイム変換
bg-primary/50 対応

Sync Logic

Figma トークン → sync-tokens 実行時、v3/v4 テーマファイルが生成される2つのパターン

var() 参照（名前が異なる変数）

テーマ変数名とCSS変数名が異なる場合、var() で直接参照します。

variables.css — ソース

--color-primary-text

var() で参照

v3/v4 テーマ — 別名で定義

--color-primary-foreground

開発者が使うクラス

text-primary-foreground

v4-theme.css

--color-primary-foreground: var(--color-primary-text)

--text-md: var(--font-size-md)

--color-foreground: var(--color-text)

v3-preset.js

primary.foreground: 'var(--color-primary-text)'

fontSize.md: 'var(--font-size-md)'

foreground: 'var(--color-text)'

CSS カスケード（同名変数）

同名変数は var() 自己参照が不可。sync-tokens が v4-theme.css の @theme に HEX フォールバック値を生成し、 variables.css（unlayered）が @layer theme より常に優先されるカスケードで上書きします。ユーティリティは var() 参照を使うため、ダークモードの変数切り替えが自動反映されます。

CSS Cascade Order

variables.css優先

unlayered — 常にカスケードで勝つ

↑ 上書き

v4-theme.csstheme layer

@theme — HEX フォールバック値

v4-theme.css (@theme = theme layer)

--color-primary: #15A0AC /* フォールバック */

--color-border: #E4E4E7

--radius-md: 6px

variables.css (unlayered = 常に勝つ)

--color-primary: #15A0AC /* 優先 */

--color-border: #E4E4E7

--radius-md: 6px

variables.css

var() 参照

var(--color-primary-text)

変数名が異なる

Colors (-foreground)Typography

CSS カスケード

#15A0AC → unlayered で上書き

同名変数

Colors (primary 等)RadiusShadow

@utility / plugins

@utility { ... var(...) }

@theme に無い項目

DurationScaleZ-indexIcon

これらの同期は sync-tokens CLI で自動生成されます。v3-preset.js / v4-theme.css を手動で編集する必要はありません。

Naming Differences

v3 と v4 ではテーマ変数の定義方法が異なります。コンポーネントが使うユーティリティクラスは同一です。

text-md

v3fontSize: { md: ['var(--font-size-md)', ...] }

v4--text-md: var(--font-size-md)

bg-primary

v3colors: { primary: 'var(--color-primary)' }

v4--color-primary: #15A0AC (cascade)

rounded-md

v3borderRadius: { md: 'var(--radius-md)' }

v4--radius-md: 6px (cascade)

text-foreground

v3colors: { foreground: 'var(--color-text)' }

v4--color-foreground: var(--color-text)

shadow-sm

v3boxShadow: { sm: 'var(--shadow-sm)' }

v4--shadow-sm: 0 1px 3px ... (cascade)

border-border

v3colors: { border: 'var(--color-border)' }

v4--color-border: #E4E4E7 (cascade)

icon-xs ~ xl

v3addUtilities plugin

v4@utility { width/height: var(...) }

v4 の @theme ネームスペースに存在しない項目（duration, scale, z-index, icon-size 等）は@utility で個別定義。 v3 では同等の機能を plugins の addUtilities() で実現しています。

v4 では *-foreground エイリアスも使用可能です（例: text-muted-foreground = text-text-muted）。shadcn/ui 等のエコシステムと互換性があります。

Custom Utilities

Tailwind 標準テーマに存在しない項目を、v3/v4 それぞれの方法でカスタムユーティリティとして定義しています。

Duration

duration-micro, duration-fast, duration-normal

トランジションの持続時間

Scale

scale-pressed

ボタン押下時の縮小アニメーション

Icon Sizes

icon-xs ~ icon-xl

5段階のアイコンサイズ

Focus Ring

focus-ring

フォーカスリングのユーティリティ

Z-index

z-modal, z-tooltip, z-toast

名前付きZインデックス

Animation

animate-checkbox-enter, animate-accordion-down

コンポーネントアニメーション

v4 — @utility（v4-theme.css に定義済み）

duration-micro

transition-duration: var(--duration-micro)

icon-xs

width / height: var(--icon-size-xs)

focus-ring

box-shadow: 0 0 0 2px var(--color-focus-ring)

v3 — plugins（v3-preset.js に定義済み）

.duration-micro

transition-duration: var(--duration-micro)

.icon-xs

width / height: var(--icon-size-xs)

.focus-ring

box-shadow: 0 0 0 2px var(--color-focus-ring)

Dark Mode

ダークモードは themes/dark.css の .dark ブロックで完全管理。v3/v4 テーマファイルにダークモード定義は不要です。

Light:root

background

text

primary

Dark.dark

background

text

primary

.dark クラスの切り替えで自動的に異なる外観に — primary 等のカラーは dark.css でトーン調整可能

v3

ユーザーの tailwind.config.js に darkMode: ['class'] を設定。 v3-preset.js は var() で参照するため、 .dark クラスで変数が切り替わると自動反映。

v4

variables.css（unlayered）が @theme（theme layer）をカスケードで常に上書き。ユーティリティは var() を使うため、.dark の変数切り替えが自動反映。 v4-theme.css に .dark ブロックは不要。

Opacity Modifier

v3/v4 両方で bg-primary/50 のような opacity modifier が使用可能。v3 は RGB チャンネル変数、v4 は color-mix() で実現されます。

100%bg-primary

75%bg-primary/75

50%bg-primary/50

25%bg-primary/25

10%bg-primary/10

v3

RGB チャンネル変数で全対応

bg-primary

bg-primary/50

text-foreground/80

border-border/50

v4

color-mix() で全対応

bg-primary

bg-primary/50

text-foreground/80

border-border/50

v3 でも bg-primary/50 のような opacity modifier に対応しています。 RGB チャンネル変数（--color-*-rgb）を自動生成して <alpha-value> を適用します。