web-css

Web CSS スキル

バージョン： 1.0 スタック： CSS 変数を使用したバニラ CSS

プリプロセッサやユーティリティフレームワークを使わず、クリーンで保守しやすい CSS を記述します。CSS 変数を使ってデザイントークンを定義します。

問題点

AI が生成する CSS にはばらつきが生じます。セッション間で記憶が引き継がれないため、似たコンポーネントでも、パディング、色、間隔、角丸がわずかに異なってしまいます。これは意図的なものではなく、それぞれ独立して作られるためです。ばらつきそのものが問題なのではありません。問題は、以降の編集がすべて部分的な修正になってしまうことです。.card の背景色を変更しても、.panel では #fff、.info-box では white、.content-block では rgb(255,255,255) が使われていると、同じ色でも形式が異なるため、更新されるのはそのうちの一つだけです。これらの標準では、値をトークンに集約し、一度の編集が全体に反映されるようにします。

利用方法

• ビルダー： CSS を書く前に ## Builder Checklist を読んでください。すべての値でトークンを使い、すべてのファイルで 5 ファイル構成に従う必要があります。
• リファクタリング担当者： ハードコードされた値や構造上の違反を見つけるには、## Enforced Rules を使ってください。トークンの命名やファイル構成に関する指針は、説明の各セクションを読んでください。
• 両者： 説明の各セクションが正式な標準です。チェックリストとルール表は、同じ内容を簡潔にまとめたものです。

---

範囲と対象外

このスキルの対象：

• デザイントークンの実装（:root 内の CSS 変数）
• トークンのカテゴリ（色、タイポグラフィ、間隔、境界線、影、アニメーション、z-index）
• CSS 変数を使ったダークモードの実装
• CSS ファイルの構成とインポート順
• BEM に着想を得た命名規則
• モバイルファーストのレスポンシブブレークポイント
• レイアウトパターン（構造には Grid、フローには Flexbox）
• コンポーネントの状態の実装
• CSS プロパティの順序
• CSS のアンチパターン

次のスキルに委ねる項目：

• design：デザインシステムの理念、Grid と Flexbox の使い分け、高品質な UI の原則
• web-accessibility：フォーカスインジケーターのパターン、動きを抑えるメディアクエリ、スクリーンリーダー用ユーティリティ

このスキルを使う場面： CSS アーキテクチャ、トークンの実装、またはレスポンシブパターンが必要な場合。 design を使う場面： デザイン原則、レイアウトの理念、またはコンポーネントの状態に関する要件が必要な場合。 web-accessibility を使う場面： WCAG への準拠や、アクセシビリティに特化した CSS パターンが必要な場合。

---

基本原則

1. まずデザイントークンを使う — すべての値は CSS 変数から取得します。
2. コンポーネント単位で管理する — CSS はコンポーネントと一緒に配置します。
3. モバイルファースト — モバイル向けの基本スタイルを定義し、上位の画面サイズに対応します。
4. マジックナンバーを使わない — すべての値に目的があり、システムから取得します。
5. 巧妙さより読みやすさを優先する — 巧妙なコードより、見てすぐ分かるコードを選びます。
6. 重複ではなく集約する — 新しいスタイルを作る前に、既存のスタイルを確認します。

---

新しい CSS を書く前に

これは必須の手順であり、推奨にとどまるものではありません。 既存のパターンと重複するクラスを新しく作るたびに、バリエーションが生まれます。バリエーションが増えると、以降の編集は一部にしか反映されなくなります。同じ目的なのに値が異なる形で別々に書かれているため、.card を修正しても .panel や .info-box を見落としてしまいます。こうして CSS は、もぐらたたきのような状態になります。ここで予防すれば、後で何時間もかけて整理する手間を省けます。

値を書く前に

1. まず global.css を確認する — この値に対応するトークンがすでにありますか？ある場合はそれを使ってください。var(--space-4)、var(--color-primary)、var(--radius-md) のようなトークンがある場合、16px、#3b82f6、8px を直接記述してはいけません。
2. 似たスタイルを検索する — 同じ用途のボタン、カード、レイアウトパターンがすでにありませんか？ある場合は再利用してください。
3. 近いものを確認する — 既存のクラスを少し調整したり、モディファイアを追加したりすれば使えませんか？
4. 繰り返しを抽出する — 同じプロパティを二度目に書こうとしている場合は、いったん止めて一つのクラスにまとめてください。

/* BAD — new class that duplicates existing .btn-primary */
.modal-submit-btn {
  padding: var(--space-2) var(--space-4);
  background: var(--color-primary);
  border-radius: var(--radius-md);
}

/* GOOD — reuse existing class, add modifier only for what's truly different */
.modal-footer .btn-primary {
  /* Only add what's actually different */
}

ドリフトが発生するパターン

パターン	危険な理由
トークンではなく生の値を使う	ある箇所では 16px、別の箇所では 1rem。同じ値でも、検索と置換では見つけられません
既存のパターンに新しいクラスを作る	.btn-primary ですでに同じことができるのに、.action-button を作ってしまいます
コピー＆ペーストして少し変更する	.card のスタイルを .panel に貼り付けて、プロパティを1つ変更すると、両者は独立して変化し、ドリフトが生じます
色の形式に一貫性がない	ある箇所では #fff、別の箇所では white、さらに別の箇所では rgb(255,255,255)。どれも同じ色ですが、検索と置換で見つかるのは1つだけです

ルール

トークンがあれば、それを使います。クラスがあれば、それを拡張します。既存のものが使えない場合に限り、新しいものを作成します。

---

デザイントークン

すべてのデザイン値は、styles/global.css の :root に CSS 変数として定義されています。トークンのカテゴリは次のとおりです。

カテゴリ	例	スケール
色 — セマンティック	--color-primary、--color-error	用途に基づく名前
色 — ニュートラル	--color-neutral-50 ～ --color-neutral-900	10段階のスケール
タイポグラフィ	--font-size-xs ～ --font-size-3xl	rem ベース
余白	--space-1 ～ --space-16	4px を基準にした 8px 刻み
罫線	--radius-sm ～ --radius-full	rem ベース
影	--shadow-sm ～ --shadow-xl	サイズスケール
Z-index	--z-dropdown ～ --z-toast	100～600
アニメーション	--duration-fast ～ --duration-slow	ms ベース

トークンの定義と値の全一覧については、assets/token-reference.md を参照してください。

ダークモード： [data-theme="dark"] でセマンティックカラーのトークンを上書きします。コンポーネントは自動的に適応します。実装方法については、assets/token-reference.md を参照してください。

---

ファイル構成

5ファイルアーキテクチャ

すべてのプロジェクトでは、カスケード順に読み込まれる5つの CSS ファイルを使用します。

styles/
├── reset.css       # 1. Browser normalization — clean slate
├── global.css      # 2. Design tokens (:root) + element defaults
├── layouts.css     # 3. Page scaffolding, grids, containers
├── components.css  # 4. All component styles (BEM)
└── overrides.css   # 5. Exceptions — one-offs, page-specific, utilities

チェック方法： check.js の css-file-count ルール（5ファイルを超えると警告、7ファイルを超えるとエラー）と css-file-names ルール（標準のファイル名が見つからない場合に警告）でチェックされます。

各ファイルの詳細（何を記述するか、何を記述しないか、内部構成）については、references/file-architecture.md を参照してください。

テンプレート

あらかじめ用意されたテンプレートファイルは、各 CSS ファイルの標準的なセクション構成を定義します。プロジェクトで変更するのは値であり、構成ではありません。

templates/
├── reset.css       # Full reset (deterministic, same for every project)
├── global.css      # Token skeleton (:root with 9 categories) + element defaults
├── layouts.css     # Section headers only (project-specific content)
├── components.css  # Pattern template (Base → Variants → States per component)
└── overrides.css   # Section headers + accessibility utilities

スキャフォールドコマンド： node scaffold-css.js <target-directory> は、5つすべてのテンプレートをコピーします。既存のファイルは上書きしません。

チェック方法： check.js の css-section-order ルール（主要なセクションが標準の順序と異なる場合に警告）と token-category-order ルール（global.css の :root 内でトークンのサブカテゴリが順序と異なる場合に警告）でチェックされます。

これはどこに記述しますか？

自問すること...	回答 → ファイル
デザイン上の意見を含まないブラウザーリセットですか？	reset.css
CSS 変数、または要素の基本スタイルですか？	global.css
ページ上で要素を配置するためのものですか？	layouts.css
BEM 命名規則を使った再利用可能な UI コンポーネントですか？	components.css
例外的なもの、一度限りのもの、または単一プロパティの上書きですか？	overrides.css
6つ目のファイルを作ろうとしていますか？	やめてください。 5つのファイルのいずれかに含めます。

---

命名規則

BEM を参考にした簡略版

.product-card { }          /* Block */
.product-card__image { }   /* Element (child of block) */
.product-card--featured { } /* Modifier (variation) */
.product-card.is-loading { } /* State (JS-toggled) */

命名ルール

種類	規則	例
ブロック	kebab-case	.user-profile
要素	__element	.user-profile__avatar
モディファイア	--modifier	.user-profile--compact
状態	.is-state	.is-active、.is-loading
ユーティリティ	u-utility	.u-visually-hidden

---

レスポンシブデザイン

• モバイルファーストのみ： min-width のブレークポイントを使います。max-width は使いません。
• 標準ブレークポイント： 640px (sm)、768px (md)、1024px (lg)、1280px (xl)
• 構造には Grid、配置には Flexbox を使います。
• すべてのインタラクティブ要素に5つの状態が必要です： デフォルト、ホバー、アクティブ、フォーカス表示、無効。

コード例（ブレークポイント、コンテナパターン、Grid／Flexbox レイアウト、コンポーネントの状態、アクセシビリティのパターン）については、assets/css-patterns.md を参照してください。

---

アンチパターン

アンチパターン	問題	解決策
値のハードコード	一貫性がなく、テーマ設定が困難です	デザイントークンを使用します
あらゆる場所での !important	詳細度の競合が発生します	セレクターの詳細度を修正します
深いネスト	上書きが難しく、詳細度の問題が起こります	階層は最大 3 レベルにします
スタイル指定での ID セレクター	詳細度が高すぎます	クラスを使用します
JS 内のスタイル	スタイルに関する関心事が分断されます	コンポーネントと一緒に CSS ファイルを配置します
グローバルな要素セレクター	すべてに影響します	コンポーネントのクラスにスコープを限定します
max-width メディアクエリ	デスクトップファーストの考え方です	min-width を使用します（モバイルファースト）
font-size のピクセル単位	ユーザー設定が反映されません	rem を使用します
レイアウトでの float	古く、壊れやすい方法です	Grid または Flexbox を使用します
兄弟要素間の余白に margin を使用	余白が積み重なり、管理しにくくなります	親要素に gap を使用します

---

プロパティの順序

プロパティをグループごとに整理します。グループは 5 つで、常に次の順序にします。

.component {
  /* 1. Positioning */
  position: relative;
  top: 0;
  z-index: var(--z-dropdown);

  /* 2. Box Model */
  display: flex;
  grid-template-columns: 1fr 1fr;
  width: 100%;
  padding: var(--space-4);
  margin: 0;

  /* 3. Typography */
  font-family: var(--font-sans);
  font-size: var(--font-size-base);
  color: var(--color-text);

  /* 4. Visual */
  background-color: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-sm);
  transform: translateY(0);

  /* 5. Animation */
  transition: box-shadow var(--duration-fast);
}

強制方法： check.js のルール css-property-order（警告）。

---

ビルダー向けチェックリスト

このスキルの対象となる CSS を記述する前に、計画が次の制約に沿っていることを確認してください。ビルダーはコードを書く前にこのセクションを読み、リファクタリング担当者は「強制ルール」表と詳細な説明を使用します。

デザイントークン

• すべての色に CSS 変数を使用する
• すべての間隔に CSS 変数を使用する
• すべてのフォントサイズに CSS 変数を使用する
• すべてのシャドウに CSS 変数を使用する
• コンポーネントの CSS に 16 進数カラーをハードコードしない
• （ボーダーを除き）ピクセル値をハードコードしない

構成

• トークンを中央のファイルで定義する
• CSS をコンポーネントと同じ場所に配置する
• BEM 形式の命名を使用する
• スタイル指定で ID セレクターを使用しない

レスポンシブ対応

• モバイルファーストにする（min-width クエリのみを使用）
• 標準のブレークポイントを使用する
• すべてのブレークポイントでテストする

アクセシビリティ

• フォーカスインジケーターを見える状態にする
• モーション軽減設定に従う
• 色のコントラストを WCAG AA に適合させる
• 色だけに頼らない

---

Tailwind なし。PostCSS なし。

このデザインシステムでは、デザイントークンを使ったバニラ CSS を使用します。ビルドツール、ユーティリティクラスのフレームワーク、プリプロセッサは使用しません。

Tailwind を使わない理由： スタイルの決定を HTML 内に移すため、クラスが肥大化し（class="flex items-center gap-4 p-6 rounded-lg bg-white shadow-md"）、コードの確認や検索が難しくなり、一か所から更新することもできません。このデザインシステムは、同じ課題である一貫性を、あるべき場所、つまり CSS 変数とセマンティックなクラス名によって解決します。

PostCSS を使わない理由： 現代の CSS は、変数、ネスト、@layer、color-mix()、コンテナクエリをネイティブでサポートしています。PostCSS は、ブラウザーがすでに処理できる機能のためにビルド工程とツールの複雑さを追加します。

プロジェクトですでに Tailwind または PostCSS を使用している場合：

1. Tailwind のユーティリティや PostCSS プラグインを追加しないでください
2. 新しい CSS は、5 ファイル構成とデザイントークンを使用したバニラ .css ファイルに記述します
3. 既存の Tailwind コンポーネントを変更する際は、ユーティリティの連鎖を components.css 内のセマンティックなクラスに抽出し、トークンを参照させます
4. 段階的に移行します。一度にすべてを書き換えるのではなく、古いパターンを拡張することも避けてください

---

適用されるルール

これらのルールは check.js（clean-team）によって決定論的にチェックされます。これらの標準を更新する際は、対応する check.js のルールも一致するように更新してください。その逆も同様です。

ルール ID	重大度	チェック内容
no-hardcoded-color	エラー	var(--color-*) の外での Hex/rgb/hsl/名前付きカラー
no-hardcoded-spacing	警告	var(--space-*) の外での生の px 間隔（>=4px）
no-hardcoded-font-size	警告	var(--font-size-*) の外でのフォントサイズ
no-hardcoded-radius	警告	var(--radius-*) の外での border-radius
no-hardcoded-shadow	警告	var(--shadow-*) の外での box/text-shadow
no-hardcoded-z-index	警告	var(--z-*) の外での Z-index
css-property-order	警告	グループ順（位置 > ボックスモデル > タイポグラフィ > ビジュアル > アニメーション）に従っていないプロパティ
css-import-order	警告	@import/<link> の順序がカスケード順と一致していない
css-section-order	警告	ファイル内の主要なセクション見出しが標準順になっていない
token-category-order	警告	global.css の :root 内のトークンサブカテゴリが順不同
mobile-first	警告	min-width ではなく max-width メディアクエリを使用
no-important	警告	!important の使用
no-id-selector	警告	#id セレクター（詳細度の競合）
unit-zero	警告	単位なしの 0 ではなく 0px/0rem を使用
css-file-count	警告/エラー	CSS ファイルが 5 個（警告）または 7 個（エラー）を超えている
css-file-names	警告	標準 CSS ファイル名（reset/global/layouts/components/overrides）がない

---

参考資料

• references/file-architecture.md — 各 CSS ファイルの詳細な説明
• assets/token-reference.md — トークンの完全な定義、使用例、ダークモード
• assets/css-patterns.md — レスポンシブ、レイアウト、状態、アクセシビリティに関するコード例