html

HTML

セマンティックで、アクセシブルかつ保守しやすく、見通しのよい HTML を記述してください。シンプルな構造と意味のある要素を優先し、不要なラッパーは最小限に抑えてください。

基本原則

コンテンツや操作に最も適した HTML 要素を使用してください。ベストプラクティスを機械的に適用しないでください。

このスキルを使う場面

次のような場合にこのスキルを使用してください。

• 生の HTML やテンプレートのマークアップを記述するとき
• ノイズの多いマークアップやラッパーの多いマークアップをリファクタリングするとき
• セマンティクス、ランドマーク、見出し構造を改善するとき
• フォームのラベル付けやコントロールの選択を修正するとき
• div、section、article、ul などの構造要素のどれを使うか判断するとき
• カスタム操作を、より適切なネイティブ HTML に置き換えるとき
• 動作を変えずに Svelte コンポーネントのマークアップを整理するとき

次のような場合はこのスキルを使用しないでください。

• CSS アーキテクチャだけに関する判断
• HTML の選択が根本的な問題でない場合の JavaScript の動作設計
• マーケティング文やコンテンツ戦略
• マークアップ構造とは関係のない、フレームワーク固有の状態管理やリアクティビティの大幅な変更

判断の順序

マークアップを記述またはレビューするときは、次の順序で判断してください。

1. コンテンツや操作に最も適した要素を選ぶ
2. カスタムの動作よりネイティブ HTML の動作を優先する
3. 構造上の価値がないラッパーを削除する
4. ラベル、見出し、ランドマーク、画像の扱いが適切であることを確認する
5. ネイティブ HTML では必要な動作を表現できない場合に限り、ARIA を追加する

テンプレートの安全性

マークアップが Svelte やその他の HTML のようなテンプレート言語内にある場合は、次の点に注意してください。

• ファイルを単独の HTML ドキュメントではなく、テンプレートのマークアップとして扱う
• {#if}、{#each}、{:else}、{@html}、bind:、class、style:、イベント属性、<svelte:head> などの特殊要素といったフレームワーク構文を保持する
• タスクで明示的に変更を求められていない限り、コンポーネントや大文字で始まるタグをネイティブ要素に置き換えない
• バインディング、キー、制御フロー、コンポーネントの境界を壊さずに、ディレクティブやブロックの周囲の HTML を改善する
• <!doctype html>、html、head、body などのドキュメント全体に関するルールは、ファイルが実際にドキュメントの外枠である場合にのみ適用する
• Svelte では、コンパイラーのアクセシビリティ警告を有用な指針として扱い、安易に svelte-ignore コメントを追加しない

ルール

1. セマンティックな要素を優先する

• コンテンツに正確に合致する場合は、セマンティックタグを使用してください。
  • header
  • main
  • section
  • article
  • nav
  • aside
  • footer
  • button
  • form
  • label
• セマンティック要素のほうが明らかに適切な場合は、div を使用しないでください
• 単なるコンテナのほうが正確な場合は、セマンティック要素を無理に使わないでください

2. 意味に基づいてコンテンツを構成する

• HTML では見た目ではなく、コンテンツの構造を記述してください
• コンテンツの内容に基づいて要素を選んでください
• ブラウザーのデフォルトのスタイルを基準に要素を選ばないでください
• ルールを満たすためだけに、余分な構造を作らないでください

3. ネストを浅く保つ

• 不要なラッパーを避けてください
• よりフラットで読みやすいマークアップを優先してください
• 階層を追加する場合は、構造、動作、スタイル上の明確な目的を持たせてください

4. 見出し階層を適切にする

• ページまたはメインビューには、明確な h1 を 1 つ使用してください
• 論理的な見出し順にしてください。
  • h1
  • h2
  • h3
• 理由なく見出しレベルを飛ばさないでください
• 文字を大きく見せる目的だけで見出しを使用しないでください

5. アクセシビリティを必須とする

• フォームコントロールには必ず適切なラベルを使用してください
• 操作には button、ナビゲーションには a を使用してください
• 情報を伝える画像には、意味のある alt テキストを追加してください
• ネイティブ HTML で問題を解決できない場合に限り、ARIA を使用してください
• 不要な ARIA は追加しないでください

6. ネイティブ HTML の動作を優先する

• カスタムな解決策より、組み込みの HTML 機能を優先してください
• 次の要素を優先してください。
  • button
  • details
  • summary
  • dialog
  • input
  • select
  • fieldset
  • table
• 汎用的な要素でネイティブコントロールを再構築しないでください

7. 読みやすいマークアップを記述する

• 一貫したフォーマットを保ってください
• インデントを明確にしてください
• 属性を読みやすくしてください
• マークアップを見通しにくくなる場合は、適宜改行してください
• ソースを読む人にとっての読みやすさを重視してください

8. クラス名には明確な目的を持たせる

• スタイル設定やスクリプトで必要な場合にのみクラスを追加します
• すべての要素にデフォルトでクラスを追加しないでください
• シンプルで意味の明確なクラス名を優先します
• 可能な場合は、見た目だけに基づく名前を避けます

9. divの入れ子を避ける

• 意味のないdiv要素を長く連ねないでください
• ラッパーが多くなった場合は、構造を見直します
• コンテナーを増やす前に簡素化します
• より適切な意味を持つ要素がない場合は、通常のdivで問題ありません

10. フォームは明示的に記述する

• すべての入力に対応するラベルを付けます
• typeの値を正しく使います
• 送信するフィールドにはnameを使います
• 入力項目をグループ化するにはfieldsetとlegendを使います
• 必須項目はテキストだけでなく、HTML属性でも指定します
• プレースホルダーテキストをラベルの代わりにしないでください

11. 内容が本当にリストである場合にのみリストを使う

• 内容が実際にリストである場合は、ul／ol／liを使います。
  • 手順
  • メニュー項目
  • 箇条書き
  • リストに属していることが重要な意味を持つ項目のグループ
• 内容が繰り返されるというだけでリストのマークアップを使わないでください
• 繰り返しだけではリストの意味にはなりません

次の場合はarticleを使います。

• 繰り返される各項目が単独で成立する
• 各項目に独自の見出し、メタデータ、または操作がある
• 繰り返される内容がカード、投稿、検索結果、記事、またはエントリーに近い

次の場合はsectionを使います。

• 内容がテーマや目的によってまとめられている
• グループに独自の見出しがあると分かりやすい
• 重要なのがリストへの所属ではなく、テーマごとのグループ化である

次の場合は通常のコンテナーを使います。

• マークアップの主な目的がレイアウトである
• より強い意味を持たせる必要がない
• リストやランドマークの意味付けが不自然になる

避けること：

• カードのグリッドをデフォルトでul／liで囲む
• 繰り返されるコンポーネントのパターンに何でもliを使う
• レイアウトだけの構造に無理に意味を持たせる

12. コンテンツと動作を分離する

• HTMLは構造を定義します
• CSSは表示を定義します
• JavaScriptは動作を定義します
• インラインスタイルや、onclick="..."のようなHTMLイベントハンドラー文字列は避けます
• テンプレート言語では、フレームワークのイベント属性を通常のインラインJavaScriptと混同しないでください

13. リンクとボタンは使い分ける

• 移動先がある場合はaを使います
• 何らかの動作を行う場合はbuttonを使います
• ボタンの代わりにクリック可能なdivやspanを使わないでください
• 実際にアプリのような動作が必要な場合を除き、単純なナビゲーションにボタンを使わないでください

14. 画像は意図を持って扱う

• 装飾画像にはalt=""を使います
• 情報を伝える画像には内容を説明するaltを指定します
• レイアウトのずれを減らすため、可能な場合は幅と高さを指定します
• キャプションがコンテンツの一部である場合は、figureとfigcaptionを使います

15. メタデータは重要

• HTMLドキュメント全体では、次を含めます。
  • <!doctype html>
  • htmlのlang
  • meta charset="utf-8"
  • meta name="viewport" content="width=device-width, initial-scale=1"
  • 内容を適切に表すtitle
• コンポーネントファイルやテンプレートの断片では、Svelteの<svelte:head>のように、フレームワークの適切な仕組みを通じてのみドキュメントのメタデータを追加します
• その他のメタデータは、明確な目的がある場合にのみ追加します

16. 意味付けを過剰に適用しない

• ルールを機械的に適用しないでください
• 「セマンティックHTML」とは、あらゆる場面で最も特化した要素を使うことではありません
• コンテンツと操作を最も正確に表す要素が、最適な要素です
• 不適切な意味付けをするより、通常のコンテナーを少数使ったシンプルな構造のほうが適切です

17. ランドマークには意味を持たせる

• ページ構造を定義するうえで役立つ場合は、main、nav、header、footer、asideなどのランドマークを使います
• 小さな各サブセクションをすべてランドマーク要素で囲まないでください
• ランドマークは情報の把握を助けるために使い、ノイズを増やさないようにします

18. 必要最小限で正確なマークアップを優先する

• 正しく機能する最小限の構造から始めます
• 意味、アクセシビリティ、保守性を向上させる要素のみを追加します
• 念のためにラッパー、ラベル、意味付けを追加しないでください

アンチパターン

• ボタンやリンクに div を使う
• ネイティブ HTML で十分な場合に ARIA を追加する
• 入力欄のラベルを省略する
• スタイル設定だけを目的として見出しを使う
• ラッパー要素を深くネストする
• レイアウトにテーブルを使う
• onclick="..." のようなプレーンな HTML インラインイベントハンドラー文字列を使う
• 有効な Svelte ディレクティブやブロックを、壊れた HTML のように書き換える
• コンポーネントファイル内に html、head、body タグを追加する
• box1、red_text、left_side のような意味のないクラス名を使う
• デフォルトでカードレイアウトを ul / li で囲む
• 内容が繰り返されるという理由だけでセマンティック要素を使う
• ナビゲーション上の価値がないランドマークを追加する
• ラベルの代わりにプレースホルダーテキストを使う

判断の目安

• 各要素が存在する理由を説明できますか？
• この div を置き換えるべきセマンティック要素はありますか？
• CSS がなくても、これは意味を成しますか？
• スクリーンリーダーで構造を理解できますか？
• 操作にはボタンを、移動先にはリンクを使っていますか？
• 見出しの順序は論理的ですか？
• フォームにはすべて適切なラベルが付き、正しくグループ化されていますか？
• ARIA は本当に必要ですか？
• これは本当にリストですか、それとも単に繰り返されるコンテンツですか？
• 繰り返される各項目は、それぞれ単独で article にできるほど独立していますか？
• 編集しているのは完全なドキュメントですか、それともコンポーネント／テンプレートの断片ですか？
• この整理によって、Svelte のディレクティブ、バインディング、ブロック、キー、コンポーネント境界が壊れませんか？
• 要素を選んでいるのは適切だからですか、それとも暗記したルールだからですか？

出力ガイドライン

HTML を記述する場合：

• まずセマンティックな構造から始める
• マークアップを最小限に保つ
• ネイティブ要素とネイティブの動作を優先する
• 可読性と保守性を高める
• 不要なラッパーを削除する
• 明確な役割がない限り、ARIA、クラス、属性を追加しない
• セマンティクスが弱い場合、ul / li、section、article を無理に使わない
• Svelte などのテンプレートファイルでは、ディレクティブ、ブロック構文、バインディング、特殊要素を保持する
• 機械的にベストプラクティスに従うより、正確な構造を優先する

推奨例

良い例

• 有用な場所でセマンティックなランドマークを使う
• ネストを浅くする
• 明示的なラベルを使う
• 論理的な見出しを使う
• ラッパーを最小限にする
• ネイティブのコントロールを使う
• 単独で成立する繰り返し項目には article を使う
• 実際のリストにのみ ul / ol を使う
• セマンティクスが最小限でよい場合はプレーンなコンテナーを使う

悪い例

• div だらけの構造
• インタラクティブでない要素をクリック可能にする
• 曖昧な構造
• 適切なセマンティクスの代わりに補助テキストを使う
• 理由のない余分なラッパー
• ネイティブ HTML で十分なのにカスタムコントロールを使う
• 繰り返されるカードすべてにリストのマークアップを使う
• 単純なレイアウトを過剰に構造化する
• セマンティクスを当てはめすぎる