ガイド：HTML/CSSで作るUI部品と小技（JSに頼らない実装）

JavaScriptのライブラリを足さずに、HTMLとCSSの標準機能でUI部品や見た目を整える小技をまとめたガイドです。AIエージェントはJSやライブラリで作りがちなので、ここにある方針をルールファイル（DESIGN.md / CLAUDE.md）に書いておくと効きます。動きについては ガイド：CSSで作る動き（アニメーション・インタラクション） を参照。

1. 部品はHTMLの標準要素で作る

• モーダルは <dialog> で開閉する モーダルはJSで開閉を作り込まず、HTMLの <dialog> 要素を使う
• アコーディオンは <details> と <summary>。name をそろえると1つずつ開く アコーディオンはJSで作らず、HTMLの <details> と <summary> で開閉させ、矢印はCSSで付ける
• カルーセルは scroll-snap で止める スマホのカルーセルは、JSのライブラリを入れずに CSS の scroll-snap でピタッと止める
• 標準要素を使うと、アクセシビリティツリーに名前と役割が出て、AIエージェントにも伝わる アクセシビリティツリーを整えると、人だけでなくAIエージェントにも理解・操作しやすいサイトになる

• 自作のドロワーや重ねるUIを開いている間は、裏側に inert を付けて操作と読み上げを止める モーダルを開いている間は、裏側の要素に HTML の inert 属性を付けて、クリックも読み上げも止める

2. フォーム

• フォーム部品のブランド色は accent-color の1行で フォーム部品のブランド色は accent-color の1行で揃える
• 郵便番号・住所・電話などに autocomplete を付けて自動入力させる フォームの郵便番号や住所の欄に autocomplete 属性を付け、スマホの自動入力で一度に埋まるようにする
• エラーは人が読める1行で、直し方まで書く エラーメッセージは「人間向けの1行」にし、謎の内部コードを並べない

3. レイアウト

• 部品は画面幅ではなく親の幅で切り替える（@container、cqi） 同じ部品を置き場所によって組み替えたいときは、画面幅ではなく親の幅を基準にする CSS の @container を使う／余白のトークンはremかpxの二択にしない。%・cqi・コンテナクエリも使い分ける
• ファーストビューは 100svh にせず、次のセクションを少し見せるか合図を置く ファーストビューで「続きがある」と伝えるため、次のセクションを少し見切れさせるか、小さな矢印を置く
• 見出しの改行は text-wrap: balance 見出しの「1文字だけ2行目」は text-wrap: balance で整える

• ナビは画面幅ではなく「実際に溢れたか」でドロワーに切り替える（animation-timeline＋スタイルクエリ） ナビが実際に収まらなくなった時だけ、JSなしでドロワーメニューに切り替える（animation-timeline＋スタイルクエリ）

4. 見た目の質感

• UI部品にも背景と3:1のコントラストを 文字だけでなく、ボタンや入力欄の枠などUI部品にも背景との3:1のコントラストを確保する
• 影はぼかし広め・濃さ薄めで、2層重ねる ボタンの影は濃くせず、ぼかしを広め・濃さを薄めにすると上品に見える
• 固定ヘッダーは半透明＋backdrop-filter で背後だけぼかす ヘッダーなどに半透明の背景と backdrop-filter を組み合わせ、背後だけをぼかしたガラスのような質感を作る
• アイコン付きボタンは見た目で余白を調整する アイコン付きボタンは、左右の余白を同じ値にせず、見た目のバランスで調整する

5. 画像

• 写真はJPEG XL、図形のはっきりしたイラストはAVIF、ビルドが多ければWebP。<picture> で別形式も用意する Webの画像形式は、写真のような画質重視ならJPEG XL、図形がはっきりしたイラストならAVIF、ビルドが多い運用ならWebPを選ぶ

ルールファイルに書く例

## UI実装のルール
- モーダルは <dialog>、アコーディオンは <details>/<summary>、カルーセルは scroll-snap。ライブラリを入れない
- フォームの入力欄には適切な autocomplete を付ける。フォーム部品の色は accent-color で指定
- ボタン・入力欄の枠などは背景と 3:1 以上のコントラスト
- 影は常時付けない。付けるなら薄く広い2層
- 画像は <picture> で AVIF / WebP を用意し、width と height を書く