css-coder

CSS コーダー

ウェブ標準、アクセシビリティ、パフォーマンス、保守性を優先して CSS を記述するためのガイダンスです。

基本原則

1. ウェブ標準を最優先する — ライブラリやフレームワークに頼る前に、ネイティブの CSS 機能を使います。明示的に依頼された場合を除き、Tailwind や CSS-in-JS は使いません。
2. アクセシビリティを必須要件とする — スタイルが支援技術を妨げず、適切にサポートするようにします。ユーザー設定（動き、カラースキーム、コントラスト）を尊重します。
3. パフォーマンスを重視する — 再描画を最小限に抑え、レイアウトスラッシングを避け、効率的なセレクターを使います。
4. 巧妙さより読みやすさを優先する — 将来のメンテナー（作者自身を含む）が、コードをひと目で理解できるようにします。
5. 暗黙的なものより明示的なものを優先する — マジックナンバーや説明のない値は避けます。共有する値にはカスタムプロパティを使います。

ワークフロー

1. まずリファレンスを確認する — CSS を書く前に、確立されたパターンやスニペットについて references/patterns.md を参照します。
2. 仕様に照らして検証する — 判断に迷った場合は、MDN Web Docs または CSS の仕様を参照します。
3. 代替案を提案する — 適切であれば、このスキルのパターン以外のアイデアも提示します。ただし、必ず上記の基本原則に沿うようにします。

記述ガイドライン

セレクター

• スタイル指定には、要素セレクターや ID セレクターよりクラスセレクターを優先します。
• 詳細度を低く、予測しやすく保ちます。
• 深いネストは避けます（最大 2～3 階層を目安にします）。

カスタムプロパティ

• 色、余白、タイポグラフィなど、繰り返し使う値には -- で始まるカスタムプロパティを使います。
• :root または適切なスコープで定義します。
• --color-primary、--spacing-md、--font-size-body のように、内容が分かる名前を付けます。

論理プロパティ

• 物理プロパティ（margin-left、padding-top、left、height など）ではなく、常に論理プロパティ（margin-inline、padding-block、inset-inline-start、block-size など）を使います。
• 論理プロパティは、国際化やさまざまな書字方向に自動的に対応します。
• 論理プロパティに相当するものがまだ存在しない場合に限り、物理プロパティを代わりに使います。

単位

• タイポグラフィと余白には rem を使います（ユーザーのフォントサイズ設定を尊重できます）。
• 適切な場合は、コンポーネントに対する相対サイズに em を使います。
• ビューポート単位（vw、vh、dvh）は必要に応じてフォールバックを用意し、慎重に使います。
• フォントサイズに px を使うのは避けます。ボーダー、シャドウ、細部には使用できます。

色

• すべての色関数（rgb()、hsl()、oklch()）には、スペース区切りのモダンな構文を使います。
• 鮮やかな色や広色域の色には、oklch() を推奨します。
• 既存の変数からホバー状態や透明度違いを導き出すには、相対カラー構文を使います。
• 構文の例については references/patterns.md を参照してください。

レイアウト

• 2 次元のレイアウト、または追加の宣言なしで垂直方向のフローが必要な場合は、CSS Grid を使います。
• 1 次元の配置には Flexbox を使います。デフォルトの方向は row である点に注意してください。
• レイアウトに float を使うのは避けます（レガシーな用途に限ります）。

メディアクエリー

• モダンな範囲構文を使います：@media (width < 48rem)、@media (width >= 48rem)。
• モバイルファーストではなく、共有スタイルを先に定義します。共通スタイルはクエリーの外に定義し、ビューポート固有のスタイルは範囲を限定したクエリー内に記述します。
• ブレークポイントは最小限に抑え、明確な必要性がある場合にのみ追加します。
• 詳しい例については references/patterns.md を参照してください。

アクセシビリティ

• スクリーンリーダーからアクセスできる状態に保つべきコンテンツを隠すために、display: none や visibility: hidden は決して使わないでください。リファレンスにある適切な手法を使います。
• prefers-reduced-motion、prefers-color-scheme、prefers-contrast を尊重します。
• 十分な色コントラストを確保します（WCAG AA を最低基準とし、AAA を推奨します）。
• フォーカスインジケーターを常に表示します。代わりのスタイルを用意せずに :focus のスタイルを削除してはいけません。

パフォーマンス

• アニメーションでは、負荷の高いプロパティを避けます（transform と opacity を優先します）。
• will-change は必要な場合に限り、控えめに使います。
• * セレクターの使用を最小限に抑えます。
• 大規模なコードベースでカスケードを管理する場合は、@layer を優先します。

参考資料

以下については、references/patterns.md を参照してください。

• 視覚的に非表示にするユーティリティ
• ユーザー設定のクエリ（動き、配色、コントラスト）
• モダンな色の構文と相対色
• Shared First のレスポンシブパターン
• プロジェクト固有の規約

パターンの追加に伴い、このファイルは拡充されていきます。必要なパターンが見つからない場合は、コア原則に沿ったパターンを提案してください。