Claude Code 2026.08.06

Tailwind CSS v4 に移行するまでに遠回りした話【Astro × Claude Code】

Astro サイトの CSS を Tailwind CSS v4 に移行しました。ただ、まっすぐ移行したわけではありません。一度は「入れない」と決めて、CSS を全部その方針で作り直して、その 3 日後に前提ごと覆しています。

この記事は、その遠回りの記録です。入れて良くなったことも、入れても解決しなかったことも書きました。

Astro を使っている人は、この記事をまるごと AI に読ませて「うちは入れる価値ある？」と聞いてみるのが早いかもしれません。移行できる割合の見積もり方と、配信量がどう変わるかは数字で入れてあります。

前提の話（WordPress をやめて Astro にしたところ）はWordPress を捨てて Astro にした話に書いてます。この記事はその続きです。

「入れない」と決めてから覆すまでの5日間の時系列

WordPress を抜けたあと、Astro サイトの保守を直していた

解説ページを増やそうとしていた

記事とは別に、AI 活用の解説を章立てで置くコーナーを作ろうとしていました（まだ中身は公開していません）。ブログ記事は 1 本 1 テーマで完結するので、順番に読んで積み上がる形には向いていないからです。

問題は、これをやるとサイトの部品が一気に増えることです。章の目次、前後の章送り、比較図、手順のステップ表示。記事にはなかったものが次々に要る。

Claude Code に保守プランを作ってもらった

部品を増やす前に、いまの状態を確認しておこうと思って Claude Code に中を見てもらいました。返ってきた数字がこれです。

src/styles/ の CSS が 17 ファイル・6,322 行。ソース全体の約 43% が CSS
一方で、見た目を自分で持っている .astro はページが 5 本だけ。部品側は 0 本
CSS クラス 639 個のうち 106 個（16%）がどこからも参照されていない
なかでも components.css は 16 クラス中 15 個が未参照

部品と見た目のつながりが、クラス名の暗黙の一致だけになっていました。部品を消しても CSS は残るので、使われないルールが積み上がっていく。しかも時間が経つほど「消していいのか判断できない CSS」に変わります。判断できないものは消せないので、そのまま残り続ける。

そこで改修プランも Claude Code に立ててもらって、その通りに進めました。使われていない CSS を検出するスクリプトを書いて自動で数えられるようにして、部品同士の依存関係も機械的に出せるようにして、見つけた改善候補は優先度つきの台帳にまとめる。「見えるようにしてから直す」の順番です。

ここまでは良かったんですが、この「その通りに進めました」が後で効いてきます。

一度は「Tailwind を入れない」と決めた

プランに沿って出した最初の決定が、「部品が自分の見た目を持つ。CSS のレイヤー機能は使わない」でした。Tailwind を入れない、という判断です。

理由は、自前のデザイントークンがちゃんと機能していたからです。色もフォントも余白も 1 箇所で管理できていて、破綻していない。動いているものを置き換えるコストを払う理由が見つからなかった。

そこから 2 日かけて、その方針で CSS を全部作り直しました。

src/styles/ を 17 ファイル 6,322 行 → 12 ファイル 1,182 行に
見た目は各部品の中へ移動（44 ファイル・5,568 行）
未参照クラスは 639 個中 106 個 → 623 個中 19 個に

数字だけ見れば大成功です。実際この時点では満足していました。

いま振り返ると、この決定の根拠は全部「自分のリポジトリの中を測った数字」だけでした。外の世界を一度も見ていません。

3日後に前提ごと覆した

参考に人のコードを見たら、全部 Tailwind だった

きっかけは、整理を進めている最中にふと気になったことでした。「そもそも一般的には、みんなどういう構成で作ってるんだろう？」

参考にしようと思って、配布されている Astro テーマをいくつか開いて中を見てみました。

見た中は、全部 Tailwind で作られていました。

Kana

あ。

CSS 設計の流派を、そこで初めて知った

そこで初めて、CSS の書き方にいくつもの流派があることを調べました。State of CSS 2025 の「CSS フレームワーク」設問（回答者およそ 4,000 人・複数選択）の結果がこうです。

ツール	回答数
Tailwind CSS	2,041
Bootstrap	1,194
フレームワークを使わない	1,061
自前フレームワーク	953
shadcn/ui	766

単一ツールとしては Tailwind が Bootstrap の約 1.7 倍で首位。でも「使わない 1,061」と「自前 953」を合わせると、素の CSS 陣営もほぼ同じ塊で残っています。

「みんな Tailwind」でもなければ「Tailwind は特殊」でもない。どっちの選択もマジョリティ。

Lyze

複数選択なので足し算はあくまで目安です。あとこの調査は CSS に関心のある層が自分から答えるアンケートなので、開発者全体の縮図ではありません。回答者 2 万人規模の Stack Overflow 2025 だと Tailwind は 21.8%。「CSS 好きの世界では過半数、開発者全体では 2 割強」という温度差があります。

補足｜そもそも Tailwind CSS とは

先に用語を揃えておきます。Tailwind CSS は、あらかじめ用意された細かいクラスを HTML 側で組み合わせて見た目を作る書き方の CSS フレームワークです。

<!-- 素の CSS：クラスに名前をつけて、別ファイルに中身を書く -->
<div class="card">...</div>

<!-- Tailwind：やりたいことを直接クラスで並べる -->
<div class="flex gap-4 rounded-lg bg-white p-4 shadow">...</div>

「HTML が汚れる」と感じる人もいれば「CSS ファイルを行き来しなくていい」と感じる人もいて、好みの問題が大きいところです。

v4 で大きく変わったのは、設定の置き場所でした。v3 までは tailwind.config.js という JavaScript ファイルで色やフォントを定義していましたが、v4 では CSS の中に直接書きます。

@import "tailwindcss";

@theme {
  --color-accent: oklch(0.81 0.07 209);
  --radius-lg: 10px;
}

自前のデザイントークンを CSS 変数で持っていた身からすると、この形は思想がほぼ同じでした。ゼロから覚え直す移行にはならない。

そのうえで、これから部品が増えていく前提で考え直しました。解説ページを作れば章の目次も図版も手順表示も必要になる。そのたびに見た目の置き場所を判断して、CSS を書いて、使わなくなったら消す。その作業が今後ずっと続くことを踏まえると、拡張性と保守性の面で Tailwind に寄せたほうが軽い、という結論になりました。

3 日後、方針を覆しました。判断を記録しておくファイル（ADR と呼ばれる形式です）には、前の決定を取り消して差し替えた旨をそのまま残しています。消さずに残すほうが、あとで「なぜこうなっているか」を追えるので。

入れるときに気をつけること

移行しながら「これは先に知っておきたかった」と思ったのが 2 つあります。どちらも後から気づくと全ファイル触り直しになるものでした。

レイヤーの順番。 CSS のレイヤーは「名前が最初に出てきた順」で強さが決まります。Astro は CSS を部品 → ページ → レイアウトの順に出力するので、放っておくとリセットが部品より強くなって見た目が崩れます。順序を宣言する 1 行を <head> の先頭に置いておく必要がありました。

レイヤー外のCSSはレイヤー付きのCSSに必ず勝つ

使える色。 Tailwind は何も指定しないと既定の 22 色 × 11 階調が使える状態になります。うちは Lint ツールを入れていないので、「勝手に色を増やさない」を意志だけで守ることになる。それは無理なので、既定のパレットを捨てて自前のトークンだけにしました。

Tailwind v4 を入れて変わったこと・変わらなかったこと

ここからが導入判断の材料です。

良くなったこと

組ごとの CSS ファイルが全部なくなった。 ブログ用・ガイド用・ツール用と分かれていた CSS が消えて、src/styles/ は横断で使う 6 ファイルだけになりました
使わないユーティリティは出力されないので、未参照 CSS が構造的に増えません（残っている手書きクラスの未参照は 2 個。数え方を途中で直しているので、前掲の 106 個・19 個との厳密な連続比較ではありません）
配布テーマ・shadcn・AI が生成したコードをほぼそのまま貼れる。移行の理由そのものではありませんでしたが、結果として一番わかりやすい変化がこれでした

解決しなかったこと

「1 系統になってスッキリ」にはなりませんでした。

Tailwind はソースをテキストとして読むので、bg-${color} のように JS で組み立てたクラス名は生成されません。うちは実行時に HTML を組み立てる画面（LoL の統計ツールなど）でそれをやっていたので、おおよそ 3 割が従来のまま残りました。2 系統が恒久的に併存します。

移行できた約7割と、クラス名を組み立てていて残った約3割

見積もるときに数えるのは、画面数ではなくクラス名を文字列で組み立てている箇所です。

配信量も増えました。記事ページで gzip 後 4.6 KB → 11.9 KB。共通ファイルに全部まとまるので、そのページで使わない分も落ちてきます。2 ページ目以降はほぼゼロ（0.9 KB → 0.07 KB）になるので回遊されるサイトなら逆転しますが、1 記事読んで帰る読者が多いうちは払うだけ。とはいえ画像 1 枚が 600 KB 超なので、桁としては誤差でした。

既存 CSS がある状態で入れるときのコスト

ゼロから作るなら関係ないけど、既存のサイトに後から入れるなら効いてくる 3 つです。

既存の CSS を全部レイヤーに入れ直す必要がある。 レイヤーに入っていない CSS は、レイヤー付きの CSS に必ず勝ちます。詳細度でも記述順でもなく仕様としてそうなので、入れ忘れた要素だけユーティリティが永久に効きません。DevTools を睨んでも理由がわからないタイプの事故です
クラス名を組み立てているところは全部書き換え。 エラーも警告も出ないまま見た目だけ消えます
リセットがブラウザの既定を消す。 h1〜h6 の文字サイズと太さ、箇条書きの行頭記号が無くなります。うちも見出しと箇条書きが実際に消えました。しかもこれは検査で拾えません。CSS としては正しく、HTML も欠けていないので、目視でしか見つからない

遠回りの反省と、遠回りしてよかったこと

正直に書くと、同じことを 2 回やっています。

前回の Astro 移行のときも、リサーチで「移行しない」と結論を出した直後に移行しました。今回も「入れない」と決めた 3 日後に入れています。

反省点ははっきりしていて、Claude Code が立てたプランを、前提から疑わずにそのまま実行したことです。

プラン自体は良くできていました。実際 CSS の整理は数字で見て改善しています。でもその計画は「自分のリポジトリの中を測った結果」だけで組まれていて、外で何が標準になっているかは材料に入っていない。そして私も、それを確かめないまま 2 日走りました。

「で、実際みんなどう作ってるの？」を一度見に行くだけで済んだ話です。所要時間でいえば数十分。それを惜しんだせいで、全部作り直してからまた書き直す羽目になりました。

AI が出した計画は、手順ではなく前提をレビューする。「何をやるか」は正しくても、「何を見ずに決めたか」までは書いてくれない。

一方で、遠回りが無駄だったかというと、そうでもなかったとも思っています。

いったん全部の CSS を部品の中へ寄せ切ったので、どの見た目がどの部品のものか自分で把握した状態になりました。おかげで移行のときに「これは移せる」「これは JS が組み立ててるから残す」を即断できています。

あと単純に、カスケードとかレイヤーとか詳細度とかを、調べるんじゃなくて踏み抜いて理解しました。レイヤー外の CSS が常に勝つ話も、記事で読んだだけなら「へえ」で終わっていたはずです。実際に自分のサイトが崩れたので忘れません。

Kana

遠回りしたけど、レベルは上がった。

効率だけで見れば損です。でも判断の速さという形で後から返ってきているので、次に同じ規模の選定をするときは、たぶんもう間違えません。

まとめ｜Tailwind v4 を入れたほうがいい人・急がなくていい人

今回わかったことを整理します。

判断が変わったきっかけは、人が作ったコードを見たこと。仕様を読んで悩むより、実物を数本開くほうが早かった
効いたのは「書きやすさ」より、これから増えるぶんの拡張性と保守性。部品が増える予定がないなら急ぐ理由は薄い
後から気づくと全ファイル触り直しになるものが 2 つある（レイヤーの順番 / 使える色）。ここは先に押さえる

判断の目安はこんな感じです。

見るところ	入れたほうがいい	急がなくていい
これからの予定	部品が増え続ける	完成していて追加予定がない
HTML の作り方	ビルド時に出し切っている	クラス名を JS で組み立てている
既存 CSS の量	少ない、またはこれから作る	多い（移行コストが重い）
外部からの取り込み	テーマ・AI 生成コードを使いたい	全部自分で書く
向いている場面	拡張の予定があるサイト	完成して安定しているサイト

うちは真ん中 2 行が思いっきり不利な側でした。それでも入れたのは、これから解説ページを増やしていく予定があったからです。逆に言うと、サイトが完成していて追加の予定がないなら、自前で書き続けるのは全然アリだと思います。移行コストだけ払って回収する場面が来ないので。

よくある質問

Q. Astro に入れる手順は？

npm install tailwindcss @tailwindcss/vite を入れて、astro.config.mjs の Vite プラグインに足すだけです。v3 用の @astrojs/tailwind は v4 では使えないので注意。うちは Astro 6 で動かしています。

Q. 既存 CSS があると、まず何が壊れる？

見出しと箇条書きです。リセットがブラウザの既定を消すので、h1〜h6 の太さと箇条書きの行頭記号が無くなります。次に多いのが「レイヤーに入れ忘れた CSS だけユーティリティが効かない」。どちらもエラーが出ないので、移行のたびに実際の画面を見る前提で進めたほうが安全です。

Q. 移行にどのくらいかかった？

方針を決めてから本番公開まで 3 日です。ただしその前に、CSS を部品へ寄せ切る作業を 2 日やっているので、実質 5 日。全部 Claude Code と一緒に進めました。

CSS の設計に正解があるわけじゃないので、この記事もあくまで「うちの場合はこうだった」です。同じところで迷ってる人の材料になれば。

次は残っている宿題（コードブロックの配色を light / dark で出し分ける件）を片付ける予定です。X でも感想聞かせてください。

この記事は役に立ちましたか？

読みたい記事をリクエストする