Tailwind CSS のトークン
アプリが Tailwind CSS v4 を使っているときは、コンポーネントの土台になっているテーマをカタログで見られます。色、スペーシング、文字、角丸、影などを、それぞれのクラスと実際の見た目のサンプルつきで一覧にします。bg-brand-500 や p-4 があるか、どう見えるかを確かめるのに使えます。設定は要りません。
ページが表示される条件
次の 2 つがそろうと、サイドバーのコンポーネントの下に「Tailwind CSS」のリンクが現れ、カタログのトップページにはエントリーごとのカードが並びます。
- Tailwind CSS 4.1.0 以降と、そのビルド用の連携パッケージが入っている。
@tailwindcss/vite、@tailwindcss/postcss、@tailwindcss/cliのどれかです。svelte-zukan はアプリの CSS をビルドするのと同じ Tailwind を読み込むので、カタログとアプリで内容がずれません。探す場所は、エントリーのあるフォルダーとその親フォルダーのnode_modules、そのあとで Vite の root のnode_modulesです - Tailwind CSS のエントリーがある。
@import "tailwindcss"(またはtailwindcss/…の import)を持つか、@themeを持つか、そのようなファイルを直接またはほかの CSS ファイルを経由して import している CSS ファイル(どのプラットフォームでも、名前が小文字の.cssで終わるもの)です。探すのは、svelte-zukan がカタログファイルを探すディレクトリ(groupsとモノレポを参照)と、Vite の root のsrcです。groupsに含まれていなくても root のsrcは探します。SvelteKit のアプリはsrc/app.cssを置き、groupsはsrc/libを指すのがふつうだからです
別のエントリーから直接、またはほかの CSS ファイルを経由して import されている CSS ファイルは、エントリーではなく部品として扱います。たとえば @import "./tw.css" と @import "./tokens.css" だけを書いた app.css があれば、エントリーは app.css で、両方のトークンが並びます。同じ部品を import する 2 つのファイルは、2 つのエントリーのままです。@reference は import に数えません。reference を付けた @import(@import "tailwindcss" reference、@import "../app.css" reference)も同じです。ファイルを theme(reference) を付けて import しているだけのファイルも、エントリーになりません。import しているだけのファイルがエントリーになるのは、そのファイルのフォルダーか Vite の root から Tailwind が見つかるときに限ります。
@theme はあっても @import "tailwindcss" がないファイルは、先頭に @import "tailwindcss"; を足して読み込みます。ほかのエントリーと同じように、Tailwind の既定値と、そのファイルのトークンが並びます。エントリーが複数あるときは、Vite の root からの相対パスを添えたリンクがエントリーごとにできます。
Tailwind が入っていない場合や Tailwind CSS v3 の場合は、ページも警告も出ず、負担もありません。4.0.x を使っているプロジェクトでは、ページにアップグレードを促すエラーが出ます(エラーを参照)。
ページに並ぶのは、エントリーから Tailwind が解決できるすべてです。既定値、@theme で追加・上書きしたもの、@plugin と @config が読み込むものが入ります。import はアプリのビルドと同じ方法で解決するので、$lib/theme.css のようなエイリアスも使えます。
カード
トップページのコンポーネントの上に、エントリーごとのカードが並びます。テーマの色を並べた帯、エントリーのファイルと Tailwind のバージョン、トークンとテーマ変数の数を載せています。パディングとスペーシングの p-4 のように 2 つのカテゴリーに載るトークンは、1 つと数えます。クリックするとページを開きます。
ページの見方
カテゴリーは左側のリストに並びます。「色」「余白とサイズ」「文字」「枠線と角丸」「効果」「レイアウト」のグループに分かれ、そのあとに「すべてのテーマ変数」が続きます。それぞれにトークンの数が付きます。幅が狭いページでは、リストがトークンの上のセレクトに変わります。カテゴリーを選んでいないときは、リストの先頭のカテゴリーが開きます。
色はテーマの順に並びます。既定のカラーパレットが Tailwind の順で並び、そのあとにプロジェクト独自の色(フィルターで探せます)、最後に current、inherit、transparent が来ます。ほかのカテゴリーは値の小さいほうから大きいほうへ並ぶので、プロジェクト独自のサイズも既定のサイズのあいだに入ります。ゼロの値や none が先頭、rounded-full が末尾です。値はブラウザーを使わずに計算し、1rem と 1em は 16px、単位のない行の高さは 16px の倍数として扱います。auto、100%、100vw、シャドウ、フォントの並びのように、この方法で比べられない値は、ほかの値のあとに来ます。値が同じトークンと、比べられないトークンは、テーマの順のままです。カテゴリーは次のとおりです。
| カテゴリー | クラス |
|---|---|
| 背景色、文字色、枠線の色 | bg-* text-* border-* |
| パディング、マージン | p-* m-* |
| フォントサイズ、フォントの太さ、フォントファミリー | text-* font-* |
| 文字間隔、行の高さ | tracking-* leading-* |
| ドロップシャドウ、ボックスシャドウ | drop-shadow-* shadow-* |
| 角丸、枠線の太さ、不透明度 | rounded-* border-* opacity-* |
| 幅、高さ、重なり順(z-index) | w-* h-* z-* |
| ブレークポイント | --breakpoint-* の変数 |
| スペーシング | --spacing の基準値と p-* のクラス |
トークンのないカテゴリーは表示しません。「すべてのテーマ変数」では、テーマ変数と宣言された値を、名前空間(--color-*、--spacing、--radius-* など。どれにも当てはまらないものは「その他」)ごとの見出しと表で見られます。色の値にはスウォッチが付き、変数名にはコピーボタンがあります。
トークンには、実際のサンプル、クラス名、CSS 変数、解決した値が載ります。サイズには計算後の px も付きます(p-4 なら calc(0.25rem * 4) · 16px)。テーマの値に --spacing(6)、--alpha()、theme(--radius-lg) などの Tailwind の CSS 関数を使っているときは、Tailwind が書き出す値(calc(0.25rem * 6))を表示します。color-mix は、フォールバックではなく、対応するブラウザー向けに Tailwind が書き出す値を表示します。Full config も、表示するクラスが読む変数については同じです。それ以外の変数、たとえば --blur-card: --spacing(2)、--ease-*、--animate-*、--aspect-*、クラスに値がコピーされる --shadow-* は、Tailwind がこの形で書き出さないので、Full config には書かれたままの値が載ります。@theme inline の変数も static を合わせて指定しない限り Tailwind が書き出さないので、Full config には書かれたままの値が載ります。@theme inline static なら、Tailwind が書き出す値が載ります。@theme { --color-brand: #f00 } に対する :root { --color-brand: #00f } のように CSS がテーマ変数を上書きしているときは、トークンにはカスケードで勝つ値(#00f)が載り、Full config と catalog.json の variables には宣言されたテーマの値(#f00)が載ります。テーマが定義していない var() は、フォールバックがあればその値で表示し(シャドウなら 0 4px 6px -1px rgb(0 0 0 / 0.1), …)、なければ書かれたままで表示します。値が空のときは none と表示します。クラス名と変数名にはそれぞれコピーボタンがあります。Tailwind に prefix を設定しているときは、クラス名にも付きます(tw:bg-brand-500)。ブレークポイントとスペーシングの基準値はクラスではないので、変数だけを表示します。変数が表示されるのは、クラスが変数を読んでいるときと、@theme inline のトークンで、クラスの値のもとになった変数があるときです。--color-primary: var(--color-blue-500) のように、@theme inline でほかのテーマ変数を参照しているトークンは、参照先ではなく自身の変数(--color-primary)を表示します。ユーティリティが複数の名前空間を読むときは、Tailwind と同じく、クラス名に一致する最初の名前空間が使われます。--color-primary と --text-color-primary があれば text-primary は --text-color-primary を、--spacing-card と --padding-card があれば p-card は --padding-card を表示します。@theme reference の変数や、@plugin と @config が読み込む変数は、Tailwind が CSS に書き出さないのでコピーするものがなく、トークンには表示しません。ただし、クラスが読む変数を CSS やプラグインが :root で宣言しているときは表示します。inline なしの @theme reference の変数と、daisyUI の base-100: var(--color-base-100) のように自身の変数を var() で参照するプラグインの値がこれにあたります。Full config には、どれも値とともに載ります。
- 絞り込み: トークンの上の入力欄に打った文字を、クラス名・変数名・値のどれかに含むトークンだけを残します。「すべてのテーマ変数」では変数名と値で絞り込みます。入力した文字はアドレスの
q(#/tailwind?source=…&category=…&q=…)に保たれるので、再読み込みしたり、リンクを共有したりしても同じトークンが表示されます。入力中は履歴を増やさず、今の履歴を置き換えます。カテゴリーを切り替えても絞り込みは残ります。絞り込んでいる間は、カテゴリー一覧の数が一致したトークンの数になり、一致のないカテゴリーは薄く表示されます - サンプルテキスト: 文字に関するカテゴリー(文字色、フォントサイズ、フォントの太さ、フォントファミリー、文字間隔、行の高さ)では、サンプルに表示する文字を入力できます
1 つのトークンに載せるクラスは 1 つだけで、そのトークンを使うすべてのユーティリティは並べません。たとえば色は bg-*、text-*、border-* だけで、ring-* や fill-* などは含みません。
サンプルの描画
背景色、文字色、文字のカテゴリーはカードで表示します。文字色のサンプルは、白に近いトークンも見えるように、明るい帯と暗い帯の両方に文字を描きます。シャドウもカードで、グレーのパネルの上に描きます。枠線の色とサイズのカテゴリー(パディング、マージン、スペーシング、幅、高さ、枠線の太さ、角丸、不透明度、ブレークポイント、重なり順)は 1 行ずつのコンパクトな表示で、見比べやすくしています。
- パディングとマージン: ブロックのまわりの余白を描きます
- 幅、高さ、スペーシング: 実際の大きさのバーを描きます。行より長いバーは、端が薄れて消えます。
100%や100vhのようにフレームに合わせて決まる値には、バーがありません - 枠線の色: そのトークンの色の太い枠線を付けた白い箱を描きます
- ブレークポイント: 幅に比例したバーを描きます。px は、メディアクエリと同じくブラウザーの初期フォントサイズ 16px で計算し、CSS がページに指定したフォントサイズには左右されません
- 重なり順(z-index): サンプルはなく、名前と値だけを表示します
サンプルは、専用のフレームの中に描きます。フレームには、Tailwind がそのエントリーから生成した CSS(テーマ変数、エントリー自身のルール、preflight)を入れています。tailwindcss/theme.css のように Tailwind のファイルの一部だけを import するエントリーでは、サンプル用に Tailwind のユーティリティを加えます。カタログのスタイルがサンプルに影響することはないので、サンプルの文字はテーマの --font-sans など、アプリの html と同じフォントで描きます。また、Tailwind の CSS がカタログやコンポーネントのプレビューに漏れることもありません。
表示する値は基本の値なので、フレームはどのカタログのテーマでも常にライトです。フレームの外のページは、カタログのテーマに従います。ただし、Full config、トップページのカード、検索の色見本はライトで描きます。
表示しないもの
- ダークモードの値。
.dark { … }や@custom-variant darkは読まないので、トークンの値は 1 つです - 任意の値とバリアント。
p-[13px]、hover:、md:は載せません。flexのようにテーマの値を取らないユーティリティも載せません - 相対パスの
@font-faceと@import url()。 サンプルはカタログの中のフレームで描くので、CSS ファイルからの相対パスで書いたurl()は解決できません。フォントファミリーのサンプルが、システムのフォントに置き換わることがあります。Web フォントの@import url("https://…")のような絶対 URL か、インストール済みのフォントなら表示できます - Tailwind CSS v3、および v4 のエントリーがない
tailwind.config.jsだけの構成
開発中の動き
データは、ページ、catalog.json、静的ビルドのいずれかが最初に必要としたときに生成します。dev サーバーの起動時には作りません。Tailwind CSS のエントリーがないプロジェクトでは、何も生成しません。
dev サーバーでは、エントリー、その import 先、プラグイン、設定ファイルが変わったとき、そして探索するディレクトリで .css ファイルが作られたり削除されたりしたときに、ページを更新します。トークンやサンプルが実際に変わったときだけ、カタログのタブを再読み込みします。アプリ自身の CSS の更新はそのまま動き、アプリのタブが再読み込みされることはありません。
次の 2 つの場合は、手を加える必要があります。
- 最初のエントリー。 dev サーバーを起動したときに Tailwind CSS のエントリーがなかった場合、あとからエントリーを作ってもページは現れません。dev サーバーを再起動してください。
- あとから作った import 先。 エントリーの
@importが、まだ存在しなかったファイルを指していたときに、探索するディレクトリの外でそのファイルを作っても、ページは自動では更新されません。エントリーを保存し直すと読み直します。
build: true にすると、静的に書き出したカタログにもこのページが入り、catalog.json にもデータが入ります。Tailwind を使わないプロジェクトでは、出力にファイルが増えません。
エラー
読み込みに失敗したエントリーは、そのページにエラーを表示します。カタログのほかの部分は引き続き動きます。vite build では、ビルドを失敗させず警告にします。同じメッセージは catalog.json のそのエントリーの error にも入ります。
| メッセージ | 対処 |
|---|---|
Tailwind CSS <version> is older than 4.1.0, the first version svelte-zukan supports |
tailwindcss と連携パッケージを 4.1.0 以降に上げます |
Tailwind CSS <version> does not expose the design-system API svelte-zukan uses |
svelte-zukan が読む API は不安定で、変わっています。svelte-zukan を更新します |
| そのほかのメッセージ | import やプラグインが解決できないなど、Tailwind が返したものです。アプリのビルドと同じように直します |
エージェント向けの同じデータは、catalog.json と WebMCP のツール list_tailwind_tokens にあります。