zpaper-draft

Type to search...

to open search from anywhere

AIエージェントにCSSを教えるためにベストプラクティスのドキュメントサイトを作った

概要

AIエージェント（Claude Code等）にフロントエンドの実装を任せると、HTMLやJavaScriptのロジックは比較的うまくいくが、CSSのコーディングで問題が起きがち。デザイントークンで「値の選択」を制約し、CSSベストプラクティスのドキュメントで「テクニックの選択」を教育する、という2つの戦略で対処するアプローチを取った。

実際にDocusaurusでCSSベストプラクティスのドキュメントサイトを構築して50記事を作り、全記事にインタラクティブなデモも追加した。そのまとめ。

AIのCSS問題

AIにデザインの再現を頼むと、見た目はそれっぽくなる。ただ、コードの品質が低い。例えばこういうパターンが繰り返される。

  • 色の値を勝手に決めてしまう（デザイントークンを使わない）
  • センタリングにtransform: translate(-50%, -50%)のようなレガシー手法をデフォルトで使う
  • flexboxで済むところにpositionを使う
  • box-shadowに単一レイヤーの不自然な影を使う
  • レスポンシブ対応で固定値を多用する
  • CSSの新しい機能（:has()、container queries、scroll-snap等）を使わない

これはCSSが本質的に「創造的な組み合わせ問題」であることに起因していると考えられる。同じ見た目を実現するCSSの書き方は無数にあり、AIにはどれが「良い」書き方なのかを判断する基準がない。

CSSの問題は2つの軸がある。

  • 値の選択 — 何の色を使うか、何のスペーシング値を使うか
  • テクニックの選択 — どのCSSプロパティの組み合わせを使うか

デザイントークンは前者を制約できるが、後者は制約できない。

戦略1: デザイントークンによるハード制約

自分のプロジェクトTakazudo Modular（zmod）では、Tailwind CSS v4のデザイントークンを厳格に制約する仕組みを作っている。

/* zmodのアプローチ: Tailwindデフォルトを全リセット */
@theme {
  --color-*: initial;
  --spacing-*: initial;
  --font-*: initial;
  /* 独自トークンのみ定義 */
  --color-zd-primary: oklch(0.65 0.24 30);
  --spacing-zd-sm: 8px;
  --spacing-zd-md: 16px;
}

Tailwindのデフォルト値をすべてワイルドカードでinitialにリセットし、--zd-*プレフィックスの独自トークンのみを定義する。ビルド時にシステム外の値を使うとエラーになる。

これにより「何の値を使うか」はAIに選択の余地がなくなる。bg-blue-500みたいなTailwindのデフォルトカラーは存在しないので使えない。bg-zd-primaryのような定義済みトークンしか選べない。

ただし、これで制約できるのは「値」だけ。「CSSプロパティの組み合わせ方」は制約できない。flexboxで済むところにpositionを使う問題や、センタリング手法の選択などはトークンでは解決しない。

戦略2: CSSベストプラクティスのスキル化

「どのテクニックを使うべきか」の知識をAIに教えるため、CSSベストプラクティスのドキュメントを大量に作り、最終的にClaude Codeのスキル（カスタムスラッシュコマンド）として使えるようにする構想。

実際に既に一部をスキル化していた。

  • /css-box-shadow-layered-natural — 自然な複数レイヤーbox-shadowの作り方
  • /css-apply-fit-content — fit-contentでボタン等をshrink-to-fitにする方法

これらは特定のCSS課題に対する「正解パターン」をAIに教えるもの。例えばbox-shadowであれば、AIがデフォルトで出してくる単一レイヤーの不自然な影ではなく、複数レイヤーを重ねた自然な影の書き方を教える。

こういうスキルをもっと体系的に増やしたかった。そのためにまず、CSSベストプラクティスを網羅的に収集するドキュメントサイトを作った。

ドキュメントサイトの構築

Docusaurus 3.9.2 + React 19 + TypeScriptで構築した。

カテゴリは8つに分けた。

  • Layout（レイアウト）
  • Typography（タイポグラフィ）
  • Spacing & Sizing（スペーシング・サイジング）
  • Color（カラー）
  • Visual Effects（ビジュアルエフェクト）
  • Responsive（レスポンシブ）
  • Interactive（インタラクティブ）
  • Modern CSS（モダンCSS）

各記事の構成はこうなっている。

  • The Problem — AIが間違えがちなパターン
  • The Solution — 推奨テクニック
  • Code Examples — 具体的なコード例
  • Common AI Mistakes — AI特有の失敗パターン
  • When to Use — 使い分けガイド

「Common AI Mistakes」セクションがある。各記事にAI特有の失敗パターンを記載していて、これをスキル化した時にAIが自分のよくやる間違いを認識できるようにしている。「こう書きがちだけど、こう書くべき」という対比が入っている。

並列エージェントでリサーチ・記事作成

50記事を手で書くのは現実的ではないので、Claude Codeのworktree teams機能（/x-wt-teams）を使った。5つのエージェントを同時に走らせて、Webリサーチから記事作成までを並列実行した。

git worktreeで5つの作業ディレクトリを作り、各worktreeでClaude Codeエージェントが独立して作業する。各エージェントがトピックPRをbase branchにマージし、最終的にroot PRをmainにマージする。合計50記事が一気に生成された。

CssPreviewコンポーネント

ドキュメントに載っているCSSコード例を実際に動かして確認できるよう、カスタムのプレビューコンポーネントを自作した。

<CssPreview
  title="Flexbox Centering"
  html={`<div class="flex-center"><div class="box">Centered</div></div>`}
  css={`
    .flex-center {
      display: flex;
      justify-content: center;
      align-items: center;
      height: 200px;
    }
  `}
/>

仕組みとしては、buildSrcdoc()がHTML/CSSを組み立て、iframeのsrcDocに渡す。sandbox="allow-same-origin"で安全に表示し、contentDocument.body.scrollHeightで高さを自動調整する。

特徴は以下。

  • iframeのsrcdocでサンドボックス化（親ページのCSSに影響されない）
  • Tailwind v4のpreflight CSSをリセットとして内蔵
  • ビューポート切り替えボタン（Mobile 320px / Tablet 768px / Full 100%）
  • CodeBlockによるHTML/CSSソースコードの折りたたみ表示
  • 高さの自動調整（コンテンツに応じてiframeが伸縮）

既存のライブラリ（Storybook等）を使わず自作したのは、Docusaurusとの統合が簡単で、依存を増やさずに済み、リセットCSSやサンドボックスの制御が自由にできるから。

全記事にデモ追加

最終的に47記事すべてにインタラクティブなCssPreviewデモを追加した。これもworktree teamsで5エージェント並列で実行した。

記事を生成するフェーズとデモを追加するフェーズを分けたのは、CssPreviewコンポーネントの仕様が固まってからデモを一括で追加したかったから。コンポーネントの設計を試行錯誤しつつ記事も書く、という並行作業にすると手戻りが多くなる。

2つの戦略の補完関係

ここまでの話をまとめると、AIのCSSコーディング品質を改善するには2つの方向からのアプローチが必要ということになる。

  • デザイントークン（値を制約） — bg-zd-primaryのような定義済みの値しか使えないようにする。AIが勝手に色やスペーシングを決めることを防ぐ
  • CSSベストプラクティスのスキル（パターンを教育） — flexboxでのセンタリング、複数レイヤーのbox-shadow、:has()の活用など、「どう書くべきか」をAIに教える

前者は仕組みで強制でき、後者はドキュメントとスキルで教育する。両方揃って初めてAIが書くCSSの品質が安定する。

今後の展望

このドキュメント群から有用なものをClaude Codeスキルとして抽出していく予定。50記事全部をスキルにするのは現実的ではないので、実際にAIが間違えやすいパターンのうち頻度が高いものから優先的にスキル化していくことになると考えられる。

既にスキル化済みの/css-box-shadow-layered-naturalや/css-apply-fit-contentは実際に使っていて、これらを指定すればAIが正しいパターンでCSSを書いてくれる。こういうスキルを増やしていく。

余談

AIを使ってAIの弱点を補う教材を作る、というメタ的な取り組みになった。ドキュメントサイト自体もClaude Codeで並列エージェントを使って構築していて、50記事+全記事デモ追加という量的な作業をこなせた。AIにCSSを教えるためのドキュメントをAIが書いている、という構図。