taste-code-craft

taste-code-craft

デザインされたページは、デザインされたコードベースです。DOM は最初に記述するレイアウトです。レイアウトと同じように構造化しましょう。

1. セマンティック HTML（DOM はデザインです）

• 1ページにつき <h1> は1つにし、見出しレベルを飛ばさずに順番に使用します（h1 → h2 → h3。h4だけを使った後にh2を置くのは禁止です）。
• 意味に合った要素を使用します。<nav>、<main>、<section aria-labelledby>、<figure>、<time>、<button>（クリックハンドラーを付けた <div> ではありません）、ナビゲーションには <a href> を使用します。
• リストには <ul>/<ol> を使います。機能を並べる場合も、5つの <div> ではなくリストにします。
• すべての <img> に alt を指定します（装飾目的の場合に限り alt=""）。また、レイアウトシフトを防ぐため、明示的に width/height を指定します。
• ラベル：すべての <input> に、画面上で見える <label>（または aria-labelledby）を付けます。placeholder だけをラベルとして使ってはいけません。
• ページに <main> がない、見出しのない <section> がある、またはクリック可能な <div> がある場合、そのページは不合格です。

2. リテラルよりトークンを使う（コード内のデザインシステム）

• すべての色、余白、角丸、影、フォントサイズは変数から指定します。コンポーネントのルールにハードコードされた16進数の色が1つでもあってはいけません。リテラルの #000 や padding: 13px が3回も出てくるなら、トークンが不足しています。
• コード内のパレットは、デザインの指定と正確に一致させます。余計なグレーを作ったり（#F4F1EA と指定されたページで #F7F8FA を使うなど）、選定されていないブランドカラーの16進数を使ったりしてはいけません。
• タイポグラフィには、コンポーネントごとに場当たり的なピクセルサイズを指定するのではなく、宣言されたスケール（rem／流動的な clamp）を使用します。
• ブレークポイントには、コンポーネントごとのマジックナンバーではなく、1つのメディアクエリ規約（幅のセットを1か所にまとめて文書化）を使用します。
• デザインシステム（taste-design-system）がある場合、コンポーネントはセマンティックトークンを使用します。プリミティブを直接参照してはいけません。

3. 特異性と CSS アーキテクチャ

• !important は使いません。必要になるなら、セレクターの構成が適切ではありません。
• ID によるスタイル指定や、副作用のある要素セレクター（section { }）は使いません。また、単一の box-sizing リセットを除き、* { } によるリセットも使いません。
• ネストの深さは最大2階層まで（またはフレームワーク独自の規約に従います）。4階層以上必要なセレクターは、存在すべきコンポーネント境界を示しています。
• ユーティリティ／インライン方式（Tailwind）は、設定がトークン化され、クラス数が読みやすく保たれていれば問題ありません。ただし、1つの要素に30個ものクラスを詰め込むのは避けてください。
• 未使用のルール：マークアップに一致する箇所がない CSS ルールは、納品前に削除します。ページには未使用のセレクターを一切残しません。
• コンポーネントは単一責任にします。UI コンポーネントごとにファイルまたはブロックを分け、1つのコンポーネントにヒーロー、フッター、モーダルの役割を持たせてはいけません。

4. インラインスタイルをゼロに（3つの例外を除く）

• レイアウト、色、タイポグラフィにインラインの style="..." を使うのは禁止です。そのためにクラスがあります。
• 許可される例外（必要最小限にし、理由をコメントに記載）：動的な値（進捗状況など、JS の状態から注入する CSS 変数）、新しいクラスを追加する必要がある単一の静的要素に対する一時的な位置調整、SVG の表示属性。
• 監査ではインラインスタイルの数を確認します。1ページに約5個を超える場合は、アーキテクチャが逸脱しています。

5. 品質管理と納品

• 不要なマークアップを残しません。未使用のラッパー div、空の要素、古いコードのコメント、console.log、本番環境に残された TODO を削除します。
• プレースホルダーのアセットは使いません。lorem テキスト、https://placehold.co、意図なく使われた unsplash の URL、404 になる画像は避けます。
• 納品するファイル：すべてのフォントは1回だけ読み込みます（taste-web-performance を参照）。すべてのスタイルシートを使用し、コピー＆ペーストで重複したフォントリンクを作らないでください。
• フォーマットを統一します（引用符のスタイル、末尾カンマの方針を統一）。フォーマッターを実行してください。フォーマットを省略するエージェントは、ほかの作業も省略している兆候です。
• マークアップによるアクセシビリティの低下を招かないでください。フォーカス可能な要素に到達できること、フォーカス可能なコンテンツに aria-hidden を適用しないこと、ボタンの中にボタンを入れないことを確認します。

6. チェックリスト（該当する場合はコードを不合格とする）

• <button>／<a>／<ul> にすべき要素が <div> になっている。
• トークンセットに含まれない色、余白、角の丸み、文字サイズがハードコードされている。
• !important、ID によるスタイル指定、または4階層以上のネストがある。
• 3つの例外以外でインラインスタイルが使われている。
• 未使用の CSS ルール、不要なマークアップ、または console.log が含まれている。
• 見出しレベルが飛んでいる、または h1 が重複している。
• alt と明示的なサイズ指定がない画像がある。
• デザインシステムを読んでいないエージェントが生成したようなコードになっている。