コンテンツにスキップ
svelte-zukan
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

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 にあります。