概要
AIエージェントにHTML+CSSのコーディングを頼むと、大体うまくいかない。デザインの再現度が低い。これはClaude Codeに限らず、どのAIでもそうで、CSSというもの自体が「正解の組み合わせ」を要求するタイプの技術だからだろうと考えている。
そこで、CSSのベストプラクティスをDocusaurusのドキュメントサイトにまとめて、AIに参照させるという試みをやった。そのまとめ。
何が問題か
「AIがCSSをうまく書けない」という問題は、定義しづらい。結果を見て初めてわかる類のもので、「自分のイメージと違う」「自分ならそうはしない」としか言えない。
デザインからHTML+CSSへの変換は、単純な変換作業ではない。構造を設計する必要がある。HTMLのセマンティクスを一旦脇に置いたとしても、柔軟で、全体として整合性のあるHTML+CSSのコンポーネントセットを組む必要がある。細部を編集しつつ、全体を見るような作業になる。
この難しさは一言で言えば「経験」で、つまらない答えだがそうとしか言えない。例えば、このスペーシングはあのスペーシングと揃えるべきか？ こういう一つ一つの判断の積み重ねが、きれいに構造化されたHTML+CSSを作る。昔はこれを丁寧にやっていた。今はCSS ModulesやScoped CSSのようなスコープ技術があるので楽にはなったが、問題がスコープの中に隠れているだけとも言える。
アプローチ
2つの方向から攻めている。
デザイントークンの制約
1つ目は、Tailwind CSSのトークンをタイトに絞ること。色、スペーシング、フォントサイズなどの選択肢を制限してしまえば、AIが変な値を使うことを物理的に防げる。
自分はどのプロジェクトでもこの方法を使っていて、Tailwind v4のデザインシステムとしてドキュメント化している。トークンの制約は「何を使うな」のガードレールになる。
トピックベースのCSS知識
2つ目が今回の本題で、CSSの書き方そのものをトピックごとにドキュメント化すること。
例えば「要素を中央揃えにする」という1つのトピックだけでも、margin-inline: auto、text-align: center、flexbox、grid、absolute positioningと、場面によって使い分ける必要がある。これをドキュメントにして「この場面ではこれ」と明示的に書く。
各記事には「Common AI Mistakes」というセクションがあって、AIがやりがちな失敗パターンを具体的に名指しで書いている。例えば「:has()で解決できる問題に対してJavaScriptでクラスを切り替える提案をする」みたいな。
作ったもの
Docusaurusで作ったCSSベストプラクティスのドキュメントサイト。
現時点でのカテゴリと主な記事は以下の通り。
- layout — flexbox、grid、centering、positioning、stacking context、subgrid、anchor positioning、negative margin expand、fit-content、aspect-ratio、gap vs margin、logical properties、clamp for sizing
- typography — fluid font sizing、line-height、text overflow、variable fonts、日本語フォント、Noto Sans webfont、screen width based font size
- color — oklch、color-mix、dark mode、currentColor、color palette strategy、contrast accessibility
- visual — layered shadows、gradients、borders、filters、clip-path、blend modes、3D transforms、
@property - responsive — container queries、fluid design with clamp、media queries、responsive grid、responsive images
- interactive — hover/focus states、transitions、scroll-snap、scroll-driven animations、
:has()、:is()/:where()、view transitions、form control styling - methodology — BEM、CSS Modules、utility class、cascade layers、custom properties advanced、tight token strategy
合計で70記事ぐらいある。各記事にはCssPreviewというコンポーネントで、ライブデモが埋め込んである。iframe内でCSS-onlyで動く。
記事の選定では、実用性を重視している。CSS nestingやCSS @scopeのような、ブラウザサポートがまだ完全でない比較的新しい機能は外した。AIに教える知識は、今すぐ使えるものでないと意味がない。
それと、AIは一般的な知識はすでに持っている。ここで必要なのは「AIがよく知らなそうなこと」と「自分がAIにこう振る舞ってほしいという方針」の2つ。この視点を忘れると、ドキュメントが際限なく膨らんで、最終的にCSS仕様書の全集みたいなものが出来上がる。それは意味がない。
記事の中身自体は、自分のアイデアをClaude Codeに伝えて、Claude Codeに書かせた。Docusaurusのサイト構築もClaude Code。自分がやったのは方向性の指示と、出来上がったものの確認ぐらい。
AIにどう参照させるか
ドキュメントを作っただけでは、AIがコーディング時にそれを参照してくれない。「どうやって参照させるか」という問題が残る。
検討したこと
いくつかの方法を考えた。
- CLIツール — zcssのドキュメントを検索するコマンドラインツールを作る案。Context7のような、知識検索のMCPサーバーを小さく作るイメージ
- MCPサーバー — 上記をMCPとして提供する案
ただ、これについてはClaude Codeからのアドバイスがあった。Claude Codeにはすでにファイル検索の機能がある。GrepやGlobで検索できるし、Readで読める。ローカルのMarkdownファイルを検索するだけなら、わざわざCLIやMCPを作る必要はない。足りないのは検索機能ではなく「いつ検索するかを知っていること」だと。
なるほどそれはそうだなということで、以下のようにした。
やったこと
Claude Codeのスキル（/css-wisdom）を作った。このスキルにはzcssの全記事のサマリーとトピックインデックスが入っている。CSSを書くときに/css-wisdomを呼べば、関連する記事を引いてくれる。スキル自体はzcssリポジトリ内に置いて、~/.claude/skills/css-wisdomからsymlinkしているので、どのプロジェクトからでも使える。
さらに、グローバルのCLAUDE.mdに「CSSを書く前に/css-wisdomを参照せよ」というルールも追加した。これで、自分が/css-wisdomを呼び忘れても、Claude Codeが自発的にドキュメントを参照する流れになっている。
まとめ
これが実際にどのぐらい効くかは、まだわからない。作ったばかりなので。
ただ、自分で読んでいて普通に楽しい。CSSの知識がきれいに整理されていると、人間にとっても読み物として良い。
世の中には毎日のようにClaude Codeのこの機能がスゴイという話があふれているが、自分はClaude Codeをうまく使うための基本は、シンプルだろうと考えている。情報をMarkdownで用意すること。これに尽きる。このCSSをうまく書かせる試みはその一例で、自分はこういうことにいつもDocusaurusを使っている。MarkdownファイルはAI用、ビューワーは人間用。必要な情報がそこにあればAIはそのように動くことが期待できる。