design

デザインスキル

バージョン： 1.0 ソース： デザイン標準

譲れないデザインとユーザーインターフェースの標準です。これは好みではなく、必須要件です。

問題

AI エージェントが、もっともらしく見えるものの一貫性のない UI を作成します。セッションごとに、余白、見出しレベル、要素の選択、状態の扱いが少しずつ異なるため、似たコンポーネントでも統一感のないインターフェースになります。ある箇所ではカードに <h3> を使い、別の箇所では <h4> を使います。ある場所ではボタンにホバー状態がありますが、別の場所にはありません。これらの標準により、どのセッションで作成されたかにかかわらず、すべての UI 要素が同じデザイン言語に従うようにします。

利用方法

• ビルダー： HTML、CSS、JSX を書く前に ## Builder Checklist を読んでください。デザイントークンの使用とセマンティック HTML は制約であり、提案ではありません。
• リファクタリング担当者： デザイン上の違反を見つけるには ## Enforced Rules を使用してください。適切な要素の選択とトークンの使用については、説明セクションを読んでください。
• 両者： 説明セクションが正式な標準です。チェックリストとルール表は、同じ内容を簡潔にまとめたものです。

---

範囲と境界

このスキルの対象：

• デザインシステムの理念と原則
• デザイントークンの使用と適用
• セマンティック HTML のパターン（要素の選択）
• CSS の書式設定と品質ルール
• コンポーネントの状態（ホバー、フォーカス、アクティブ、無効）
• レイアウトの考え方（Grid と Flexbox の選択）
• レスポンシブデザインの原則とブレークポイント
• プレミアム UI の理念とアンチパターン

他のスキルに委ねる内容：

• web-accessibility：WCAG 準拠の詳細、スクリーンリーダーのパターン、ARIA の使用、キーボード操作
• web-css：CSS アーキテクチャ、ファイル構成、命名規則（BEM）、ダークモードの実装

このスキルを使う場面： デザイン原則、トークンの適用、またはセマンティック HTML の指針が必要な場合。 web-accessibility を使う場面： WCAG 準拠、スクリーンリーダーのサポート、またはフォーカス管理が必要な場合。 web-css を使う場面： CSS の整理、変数のアーキテクチャ、またはレスポンシブ対応の実装詳細が必要な場合。

---

基本原則

1. ユーザー第一 — ユーザーのニーズ、ワークフロー、使いやすさを優先します
2. 細部まで丁寧に作り込む — すべての UI 要素で精度と完成度を追求します
3. 速度とパフォーマンス — 読み込みを速くし、操作にすばやく反応します
4. シンプルさと明瞭さ — クリーンなインターフェースと、曖昧さのないラベルを実現します
5. 集中と効率 — ユーザーがすばやく目標を達成できるようにします
6. 一貫性 — 全体を通じて統一されたデザイン言語を保ちます
7. アクセシビリティ（WCAG AA） — すべてのユーザーを包摂するデザインにします
8. 明確なデフォルト設定 — 熟慮されたデフォルト設定により、選択による負担を軽減します

---

デザインシステム（信頼できる唯一の情報源）

重要なルール

1. 必ずデザイントークンを使用すること — ハードコードされた値は決して使用しないこと
2. すべての値は styles/global.css に由来すること — CSS 変数の信頼できる唯一の情報源です
3. マジックナンバーを使わないこと — 色、余白、サイズにはすべて CSS 変数を使用します

例

/* ✅ Correct - Uses design tokens */
.button {
  padding: var(--space-sm) var(--space-md);
  font-size: var(--font-size-body);
  background: var(--color-primary);
  border-radius: var(--radius-sm);
  box-shadow: var(--shadow-sm);
}

/* ❌ Wrong - Hardcoded values */
.button {
  padding: 8px 16px;           /* Use var(--space-sm) var(--space-md) */
  font-size: 14px;             /* Use var(--font-size-body) */
  background: #3B82F6;         /* Use var(--color-primary) */
  border-radius: 4px;          /* Use var(--radius-sm) */
}

デザインシステムの内容

• 完全なカラーパレット（ニュートラルカラー、セマンティックカラー、ダークモード）
• 完全なタイポグラフィスケール（フォント、サイズ、ウェイト、行の高さ）
• 余白システム（4px を基準）
• 角丸
• シャドウ
• Z インデックスレイヤー
• アニメーションの時間とイージング
• アイコンサイズ
• ブレークポイントの値

---

セマンティック HTML

必須事項

1. セマンティックタグを使用します：<header>、<nav>、<main>、<article>、<section>、<footer>
2. 操作にはボタン（<button>）、ナビゲーションにはリンク（<a>）を使用します
3. フォームでは <form>、<label>、<input>、<select>、<textarea> を使用します
4. リストには <ul>、<ol>、<li> を使用します（箇条書き用の div は使用しません）
5. 見出しは階層に沿って使用します：<h1> → <h2> → <h3>（レベルを飛ばさないこと）
6. 画像には内容を説明する alt テキストを設定します
7. 表形式のデータには適切なマークアップを使用します

例

<article class="product-card">
  <header>
    <h2>Product Name</h2>
  </header>
  <img src="..." alt="Product description">
  <p>Product description goes here.</p>
  <footer>
    <button type="button">Add to Cart</button>
  </footer>
</article>


<div class="prd-crd">
  <div class="hdr">
    <div class="ttl">Product Name</div>
  </div>
  <div class="img"></div>
  <div class="btn">Add to Cart</div>
</div>

---

HTML の整理

見出しは構造を示すために使う

見出し（<h1>～<h6>）は文書の構造を定義するものであり、視覚的なスタイル設定に使うものではありません。

<h3>Sale Price</h3>  


<p class="price-label">Sale Price</p>

クラスの付けすぎを避ける

要素に付けるクラスは 1～3 個にします。4 個を超える場合は見直しが必要です。セマンティッククラスにまとめてください。

<button class="px-4 py-2 bg-blue-500 text-white rounded-md hover:bg-blue-600 focus:ring-2">
  Submit
</button>


<button class="btn btn--primary">
  Submit
</button>

インラインスタイルなし

HTML は構造を記述し、CSS は見た目を扱います。両者を分離してください。

// ❌ Bad - Inline styles
<div style={{ marginTop: '16px', padding: '8px' }}>

// ✅ Good - CSS class
<div className="card-section">

唯一の例外： 実行時に計算される、真に動的な値です。その場合でも、CSS カスタムプロパティを優先してください。

---

CSS の品質

書式ルール

1. 1 行につき 1 つのプロパティ
2. ハードコードされた値ではなく、デザイントークン（CSS 変数）を使用する
3. 論理的なプロパティの順序：配置 → ボックスモデル → タイポグラフィ → 視覚効果 → アニメーション
4. 説明的なクラス名（BEM またはセマンティックな命名）
5. ルールセット間に十分な余白を設ける
6. 複雑なセクションにはコメントを付ける

例

/* ✅ Good - Human-readable */
.product-card {
  display: flex;
  flex-direction: column;
  gap: var(--space-md);
  padding: var(--space-lg);
  background-color: var(--color-neutral-50);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-sm);
}

.product-card:hover {
  box-shadow: var(--shadow-md);
  transform: translateY(-2px);
  transition: all var(--duration-fast) var(--easing-standard);
}

---

コンポーネントの状態（必須）

すべてのインタラクティブなコンポーネントには、次の 5 つの状態が必須です。

状態	要件	例
デフォルト	基本の外観	通常のボタン
ホバー	マウスオーバー時の視覚的フィードバック	背景色が暗くなる
アクティブ	押下時の視覚的フィードバック	少し縮小する
フォーカス	明確なフォーカスインジケーター（キーボード操作）	outline: 2px solid var(--color-focus); outline-offset: 2px;
無効	視覚的に区別でき、操作できない状態	グレー表示、低い不透明度

---

レイアウトの考え方

CSS Grid と Flexbox

レイアウトの要件	ツール	例
ページ構造	Grid（名前付き領域）	ヘッダー、サイドバー、メイン、フッター
セクションのレイアウト	Grid（名前付き領域）	2 列のコンテンツ、フォームのレイアウト
コンポーネントの構造	Grid（名前付き領域）	カード内部、モーダルのレイアウト
ナビゲーション項目	Flexbox	上部ナビゲーション項目、メニュー項目
ギャラリー／流動的に並ぶ項目	Flexbox	画像グリッド、カードギャラリー、タグリスト

構造には Grid をデフォルトで使用してください。 項目を流し込む、分散する、または折り返す必要がある場合は Flexbox を使用してください。

名前付き領域を使用した Grid（主要なレイアウト方法）

#app-layout {
  display: grid;
  grid-template-columns: 200px 1fr;
  grid-template-areas:
    "header header"
    "sidebar main"
    "footer footer";
  gap: var(--space-md);
}

#header { grid-area: header; }
#sidebar { grid-area: sidebar; }
#main { grid-area: main; }
#footer { grid-area: footer; }

余白

• 明瞭さを高めるため、十分な余白を設ける
• デザイントークンを使用して、余白を一貫させる

---

アクセシビリティ（WCAG AA）

必須基準

1. 色のコントラスト

   • 通常のテキスト：最小 4.5:1
   • 大きなテキスト（18px 以上）：最小 3:1

2. キーボード操作

   • すべての機能をキーボードから利用できる
   • 論理的なタブ順序
   • フォーカスインジケーターが見える

3. スクリーンリーダーのサポート

   • 適切な ARIA ラベル
   • セマンティック HTML
   • ナビゲーション用のスキップリンク

4. フォームのラベル

   • すべての入力に対応するラベルがある
   • エラーメッセージが入力項目に関連付けられている

ユーザーの設定を尊重する

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

---

レスポンシブデザイン

モバイルファーストのブレークポイント

/* Mobile: 0-767px (base styles, no media query needed) */

/* Tablet: 768px and up */
@media (min-width: 768px) { }

/* Desktop: 1024px and up */
@media (min-width: 1024px) { }

/* Large Desktop: 1280px and up */
@media (min-width: 1280px) { }

使用禁止： @media (max-width: ...) — 必ず min-width を使用してください（モバイルファースト）。

コンテナーの最大幅

• モバイル：100%（パディングあり）
• タブレット：768px
• デスクトップ：1024px
• 大型：1280px

---

プレミアム UI の考え方

S-Tier SaaS の基準（Stripe、Airbnb、Linear）に従います。

• 完璧な余白を備えた洗練されたタイポグラフィ
• さりげないグラデーションを取り入れた上質なカラーパレット
• 意図を持ったアニメーション（150～300ms）
• 心地よいマイクロインタラクション
• 細部への徹底したこだわり

目標： すべてのインターフェースに上質さを感じさせることです。派手な効果ではなく、さりげない洗練を重視してください。

---

アンチパターン（絶対に避けること）

アンチパターン	問題点	代わりに行うこと
フローティングラベル	混乱を招く	入力欄の上にラベルを配置する
インラインバリデーション	煩わしい	フォーカスが外れたとき／送信時に検証する
汎用的なエラーメッセージ	役に立たない	具体的で、対処方法が分かるエラーを表示する
重要な情報にツールチップを使う	見落としやすい	情報を直接表示する
理由の説明がない無効なボタン	不満を招く	無効になっている理由を示す
カスタムスクロールバー	UX に一貫性がない	システムのスクロールバーを使用する
デスクトップでのハンバーガーメニュー	ナビゲーションを隠してしまう	デスクトップではナビゲーション全体を表示する

---

ビルダー用チェックリスト

このスキルが適用される UI コードを書く前に、これらの制約に照らして計画を確認してください。ビルダーはコードを書く前にこのセクションを確認し、リファクタリング担当者は「強制ルール」表と本文全体を参照してください。

デザインシステム

• すべての値にデザイントークンを使用する
• マジックナンバーやハードコードされた色を使用しない
• デザインシステムを信頼できる唯一の情報源とする

セマンティック HTML

• セマンティックタグを適切に使用
• アクションにはボタン、ナビゲーションにはリンクを使用
• 見出し階層に従う
• すべての画像に代替テキストを設定

CSS

• 人が読みやすい書式
• デザイントークンを全体で使用
• 論理プロパティの順序を統一

コンポーネントの状態

• デフォルト状態を実装
• ホバー状態を実装
• アクティブ状態を実装
• フォーカス状態を実装
• 無効状態を実装

アクセシビリティ

• 色のコントラストが WCAG AA に準拠
• キーボード操作が可能
• スクリーンリーダーでテスト済み
• フォーカスインジケーターが見える
• フォームラベルを設定

レスポンシブ対応

• モバイルファーストのアプローチ
• 標準のブレークポイントを使用
• すべての画面サイズで動作

アンチパターンの回避

• フローティングラベルを使用しない
• インラインバリデーションを使用しない
• 汎用的なエラーメッセージを使用しない
• 重要な情報にツールチップを使用しない
• 説明のない無効状態のボタンを設置しない
• カスタムスクロールバーを使用しない
• デスクトップでハンバーガーメニューを使用しない

---

適用されるルール

これらのルールは check.js（clean-team）によって決定論的にチェックされます。これらの標準を更新する際は、対応する check.js のルールも一致するように更新してください。その逆の場合も同様です。

ルール ID	重大度	チェック内容
no-inline-style	error	HTML 内の style="..." 属性
no-jsx-inline-style	warn	JSX 内の style={{...}}
button-type-required	error	type 属性のない <button>
doctype-required	error	<!DOCTYPE html> がない
max-classes	warn	要素に 4 個を超えるクラスがある

---

参考資料

• references/semantic-html.md — セマンティック HTML 完全ガイド
• references/css-formatting.md — CSS のベストプラクティス
• references/accessibility-guide.md — WCAG AA 準拠
• references/responsive-breakpoints.md — レスポンシブデザインのパターン

アセット

• assets/component-states-checklist.md — 状態の実装ガイド
• assets/anti-patterns.md — アンチパターンの詳細な説明
• assets/layout-examples.md — CSS Grid と Flexbox の例

スクリプト

• scripts/validate_design_tokens.py — ハードコードされた値をチェック
• scripts/check_accessibility.py — 基本的なアクセシビリティ検証