執筆スタイル
このドキュメントでは、CSSベストプラクティス記事の執筆スタイルを定義します。すべての記事の一貫性、明確さ、AIエージェントにとっての有用性を保つために、これらのルールに従ってください。
対象読者
主な読者は、CSSパターンを学ぶためにこれらの記事を参照するAIエージェントです。人間の開発者もドキュメントの閲覧・管理を行います。両方の読者を想定して執筆してください：機械にとって十分に正確で、人間にとって十分に明瞭な文章を心がけましょう。
トーン
- プロフェッショナル、教育的、簡潔であること
- 冗長な言葉、不要な曖昧表現、会話的な余計な表現を避ける
- 受動態より能動態を使う
- 長い文より短い文を使う
- 事実を述べる。主観的な意見は書かない
OK/NG：トーン
OK（簡潔）：
Flexboxによる中央配置には、親コンテナに定義された高さが必要です。
NG（曖昧、冗長）：
Flexboxによる中央配置を使用する際には、親コンテナに定義された高さを設定することを検討した方がよいかもしれない点に注意する価値があるでしょう。
OK（能動態）：
ブロック要素を水平方向に中央配置するには、
margin-inline: autoを使用します。
NG（受動態）：
ブロック要素は、
margin-inline: autoを使用することで水平方向に中央配置することができます。
記事の構成
すべての記事は以下のセクション順序に従います。すべてのセクションが必須ではありませんが、順序は維持する必要があります。
1. 問題
記事が対処するよくある間違いや誤解から始めます。何がうまくいかないのか、なぜそれが重要なのかを述べます。このセクションは、解決策を提示する前に、読者に実際の問題を理解させるためのものです。
2. 解決策
アプローチを概要レベルで説明します。簡潔に保ちましょう — 詳細はコード例に含めます。
3. コード例
CSSコード（および必要に応じてHTML）をインラインコメント付きで示します。それぞれの技法には独自のサブ見出しを付けます。各コードブロックの後にCssPreviewデモを配置します。
4. ライブプレビュー
上のコード例にインラインで配置されていない場合は、CssPreviewコンポーネントをここにまとめます。デモは、対応するコードのすぐ横にインラインで配置することを推奨します。
5. クイックリファレンス
シナリオと推奨技法のマッピングをまとめた表です。「シナリオ」と「技法」の2列の表を使用します。
6. AIのよくある間違い
この記事の技法を適用する際にAIエージェントが犯しがちな具体的なミスをリストします。ミスを太字にし、その後に説明を記述します。
7. 使用場面
技法ごとに整理した判断ガイダンスです。各技法にサブ見出しを使い、説明は1〜2文に収めます。
8. Tailwind CSS
TailwindPreviewコンポーネントを使ったTailwindの対応クラスです。任意 — 記事がTailwindユーティリティに直接対応するCSSプロパティを扱う場合のみ含めます。
9. 参考資料
MDN、web.dev、CSS-Tricksなど、信頼性の高いソースへの外部リンクです。
CssPreviewデモ
すべてのCSSコンセプトには、対応するCssPreviewデモが必要です。デモは各記事の最も価値のある部分です。文章よりもデモを多くすることを推奨します。
デモのルール：
- CssPreviewはJavaScriptなしのiframe内でレンダリングされます — すべてのインタラクションはCSS専用です（
:hover、:focus、:checkedなど） - カラーは
hsl()を使用し、16進数は使わない - 記述的なBEM風のCSSクラス名を使用する（例：
.card__title、.flex-center、.grid-sidebar） - デモは最小限に — 説明している技法のみを表示する
- すべてのデモには記述的な
titleプロパティが必要
OK/NG：デモのカラー
OK：
background: hsl(210, 50%, 95%);
color: hsl(210, 80%, 40%);
NG：
background: #f0f4f8;
color: #2563eb;
執筆ルール
問題から始める
記事はうまくいくことではなく、何がうまくいかないかから始めます。AIエージェントは「Xをする方法」よりも「YだからXをしてはいけない」という形式の方がよく学習します。
1記事1コンセプト
各記事は1つのCSS技法またはパターンを扱います。トピックに十分な深さがある場合は、ディープ記事パターン（index.mdx + サブページのフォルダ）を使用します。
主観的な判断を避ける
「これはエレガントだ」「これが最良のアプローチだ」とは書かないでください。技法が何をするのか、いつ使うのか、トレードオフは何かを述べてください。
OK/NG：主観的な表現
OK（事実に基づく）：
place-items: centerは最も簡潔な中央配置の構文です — 1つの宣言で2つを置き換えます。
NG（主観的）：
place-items: centerは中央配置の問題に対するエレガントで美しい解決策です。
汎用的なCSS知識の繰り返しを避ける
読者が基本的なCSSを理解していることを前提とします。display: flexが何をするかを一から説明しないでください。記事のトピックに特有のパターン、トレードオフ、よくある間違いに焦点を当ててください。
比較にはテーブルを使う
複数のアプローチを比較する場合は、文章ではなくテーブルを使用します。テーブルはAIエージェントにとって解析しやすい形式です。
コードを先に、文章を後に
コードを最初に示し、その後に説明します。読者（特にAIエージェント）は、説明なしでもコードを理解できることが多いです。文章はコードだけでは伝わらないコンテキストを補足します。
ディープ記事パターン
トピックに複数のサブページを必要とする十分な深さがある場合、フラットな.mdxファイルをフォルダに変換します：
docs/layout/centering-techniques/
index.mdx # 概要 + ナビゲーション
margin-auto.mdx # margin: autoのサブページ
flexbox.mdx # Flexbox中央配置のサブページ
grid.mdx # Grid中央配置のサブページ
index.mdxは各サブページへのリンクと簡単な概要を提供します。