UI/UXデザインガイドライン・データモデル設計標準と基本原則

UI/UXデザインガイドラインとは

UIコンポーネントとデザイントークンの標準化は、一貫したユーザー体験を生む基盤です。エンジニアとデザイナーが共通の語彙を持つためにも重要で、「デザインがある」「実装がある」という二重管理を防ぐ役割も担います。

デザインガイドラインがないと何が起きるか

「このボタンのパディングって何pxですか？」「青系の色は #0066CC と #1A7FE8 のどっちを使えばいいですか？」「ローディング中はスピナーを出すんですか？それともスケルトンですか？」こういった質問がSlackに毎日流れるようになったら、デザインガイドラインが必要なサインです。

デザイントークンによる値の統一

デザイントークンとは、カラーパレット・タイポグラフィ・スペーシング・シャドウなどをCSS変数（または設計システムの変数）として定義したものです。コード内でのハードコードを禁止することで、テーマ変更（ダークモード対応など）が一箇所の変更で済むようになります。

CSS — デザイントークンの使用例

/* ❌ Bad: 値をハードコード（変更時に全箇所を修正する必要がある） */
.button {
  background-color: #0066CC;
  padding: 8px 16px;
  border-radius: 4px;
  font-size: 14px;
}

/* ✅ Good: デザイントークンを使用（変数定義を変えるだけで全体が変わる） */
.button {
  background-color: var(--color-primary-500);
  padding: var(--spacing-2) var(--spacing-4);
  border-radius: var(--radius-sm);
  font-size: var(--text-sm);
}

/* ── トークン定義例 ── */
:root {
  --color-primary-500: #0066CC;
  --color-primary-600: #0055A5;
  --spacing-2: 8px;
  --spacing-4: 16px;
  --radius-sm: 4px;
  --text-sm: 0.875rem;  /* 14px */
}

コンポーネント設計の原則（Atomic Design）

Atomic Designを採用し、コンポーネントを粒度で分類する方針を定義します。「このUIはどこに置くべきか」という判断が明確になり、同じようなコンポーネントが複数箇所に散在する「スパゲッティUI」を防げます。

レベル	粒度	例	特徴
Atoms	最小単位	Button, Input, Icon, Label	それ以上分解できない。状態（disabled, hover）を持つ
Molecules	Atomsの組み合わせ	SearchBar（Input + Button）, FormField（Label + Input + ErrorText）	単一の責務を持つ小さなUIブロック
Organisms	Molecules/Atomsの組み合わせ	Header, ArticleCard, CommentSection	ページの一部として独立して機能するUI
Templates	ページのレイアウト骨格	TwoColumnLayout, SingleColumnLayout	コンテンツをどこに配置するかを定義。データを持たない
Pages	実際のページ	ArticleDetailPage, UserProfilePage	データをTemplateに注入する。ルーティングの単位

インタラクション設計の統一

「ローディング中はどう表示するか」「エラー時はどう見せるか」というインタラクションの統一ルールを明文化します。コンポーネントごとにバラバラだと、ユーザーが「同じアプリなのに操作感が違う」と感じる原因になります。

Text — ローディング状態の統一ルール

ローディング状態の統一ルール:
- 200ms以内に完了する処理: ローディング表示なし（フラッシュを防ぐ）
- 200ms〜2秒の処理: スピナー表示（中央寄せ or ボタン内）
- 2秒を超える処理: スケルトンスクリーン + 進捗メッセージ

エラー状態の統一ルール:
- フォームバリデーション: 送信後に各フィールド直下に赤テキストで表示
- APIエラー（4xx）: トースト通知（右上、3秒で自動消去）
- APIエラー（5xx）: フルページエラー画面またはインラインエラーバナー
- ネットワークエラー: 再試行ボタン付きエラーメッセージ

WCAG 2.1 AA準拠を最低基準とし、具体的な数値と実装要件をガイドラインに明記します。「アクセシビリティに対応する」という曖昧な指示より、数値で示すことで実装者が判断できます。

カテゴリ	基準	実装要件
色のコントラスト	テキスト: 4.5:1以上大きなテキスト（18pt+）: 3:1以上	背景色と文字色の組み合わせをColorReview等で検証
キーボード操作	すべての操作がキーボードで完結できること	フォーカスリングを可視化（`:focus-visible`）、Tabキーの移動順序が論理的であること
スクリーンリーダー	意味のある画像に代替テキスト	`alt`属性、`aria-label`、`role`属性の適切な使用
タッチターゲット	タッチ操作の対象は44px × 44px以上	スマホでの誤タップを防ぐ最小サイズを保証する

データモデル設計標準とは

データモデルは一度定義すると変更コストが高いため、初期段階での標準化が特に重要です。スキーマの命名がバラバラだと、SQLを書くたびに「このカラムは user_id か userId か user か」と迷う事態になります。

テーブル命名とカラム定義のルール

SQL — テーブル定義の Good / Bad 比較

-- ✅ Good: 標準的なテーブル定義
CREATE TABLE articles (
  id           BIGSERIAL PRIMARY KEY,
  title        VARCHAR(255) NOT NULL,
  body         TEXT NOT NULL,
  author_id    BIGINT NOT NULL REFERENCES users(id),
  published_at TIMESTAMPTZ,          -- NULLの場合は下書き
  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- ❌ Bad: 命名が不統一な定義
CREATE TABLE Article (               -- 単数形・PascalCase
  ArticleID INT PRIMARY KEY,         -- カラム名がPascalCase
  ArticleTitle VARCHAR(255),         -- NOT NULL制約なし
  CreatedDate DATETIME               -- タイムゾーン情報なし
);

ルール	説明
テーブル名はスネークケース・複数形	`users`, `article_comments`, `user_sessions`
全テーブルに`id`（PK）必須	BIGSERIAL（自動インクリメント）またはUUID。選択の根拠もドキュメント化
全テーブルに `created_at` / `updated_at` 必須	`TIMESTAMPTZ`型でタイムゾーン付き。`DEFAULT NOW()` で自動設定
外部キー名は `参照テーブル名_id`	`user_id`, `article_id`（省略形・独自名は禁止）
NULL許容は明示的に設計する	「NULLの意味」をコメントに記載する（例: `published_at` がNULLなら下書き状態）

論理削除 vs 物理削除の方針

論理削除（deleted_atカラムで削除フラグを管理）と物理削除（レコードをDELETE）のどちらを採用するかをチームで統一します。混在すると「このテーブルはどっち？」と毎回確認が必要になります。

論理削除の落とし穴

論理削除を採用する場合、全クエリに WHERE deleted_at IS NULL が必要になります。これを書き忘れると削除済みデータが表示される重大なバグになります。対策として、ORMのデフォルトスコープ（Railsの default_scope、Laravel の SoftDeletes、Prismaの softDeleteミドルウェアなど）をセットで定義し、生SQLを使う場合のチェックリストも用意しておきます。

マイグレーション管理ルール

Text — マイグレーションルール

マイグレーションルール:

1. すべてのマイグレーションはup/downをセットで書く
   （ロールバックできない変更はリスクが高い）

2. NOT NULL制約の追加は2ステップで行う
   Step1: デフォルト値を設定してカラム追加（NULLを許可）
   Step2: データ埋め戻し後にNOT NULL制約を追加
   ※ 大量データのテーブルへの直接のNOT NULL追加はロックが発生するため

3. インデックス追加は CONCURRENTLY オプションを使用する
   CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
   ※ 本番でのテーブルロックを防ぐ

4. カラム削除は即座に行わず、3ステップで安全に進める
   Step1: アプリケーション側でカラムの書き込みを停止
   Step2: 1リリース後、読み取りも停止
   Step3: 次のリリース後にカラム削除のマイグレーションを実行

どれから始めるか（優先度の考え方）

全種類を一度に整備しようとすると挫折します。チームの現状の課題から逆算して優先順位を決めましょう。

チームが直面している課題	最初に整備すべきもの
コードレビューで毎回同じ指摘が出る	コーディング規約
APIの仕様がチームごとに違う	API設計ガイドライン
新メンバーがアーキテクチャを理解できない	アーキテクチャ設計標準 + ADR
UIが画面ごとにバラバラ	UI/UXデザインガイドライン
DBスキーマが混沌としている	データモデル設計標準
「昔なんでこうしたんだっけ」が頻出する	ADRの整備

1つに集中してから広げる

まず1つの領域に集中し、チームで使える状態にしてから次に広げることが成功の鍵です。「全部やろう」は「全部中途半端」になります。最初の1つが「機能している」という実績を作ることで、チームの温度感も上がります。

ドキュメント構成の基本原則

どの種類の設計標準ドキュメントを書く場合にも共通する、構成の基本原則があります。

対象読者を明確にする：「誰のためのドキュメントか」を最初に明示します。同じ「コーディング規約」でも、新卒エンジニア向けの説明と、経験豊富なメンバー向けの説明では粒度が異なります。対象読者が不明確なドキュメントは、誰にとっても中途半端になりがちです。

「Why（なぜ）」を先に書く：ルールだけを列挙したドキュメントは「守らなければならない規則集」になります。背景・理由を先に書くことで「なぜこのルールが存在するのか」が伝わり、例外的なケースで自律的な判断ができるようになります。

例外・アンチパターンも明記する：「原則〇〇だが、△△の場合は例外」という記述がないと、現場が迷います。また「やってはいけないこと（アンチパターン）」を明示することで、過去に起きた問題の再発を防ぐ役割も果たします。

バージョン管理と更新フロー：ドキュメントにも「いつ、誰が、何を変えたか」の履歴が必要です。Gitで管理し、変更はPRベースでレビューするフローが理想です。ドキュメントのフロントマター（ヘッダーメタデータ）に last_reviewed と next_review を記載し、最新性を可視化します。

次のPARTで扱うこと

PART 04では、設計標準ドキュメントの「書き方」を実践的に解説します。使えるテンプレート全体像、「なぜ」の書き方、Good/Bad例の添え方、例外・アンチパターンの記述方法、チェックリストの作り方まで、実際に書けるようになるための具体的な手順を学びます。