design-led-development

デザイン主導の開発

必然性と信頼感があり、使っていて楽しいシステムを構築します。コードのすべての行が、人にとっての成果につながります。

中核となる判断フレームワーク

機能を実装する前に、次の質問に順番に答えます。

1. ユーザーの成果：「これは、[ユーザー] が [仕組み] によって [成果] を達成するのに役立ちます」
2. 不安とコントロール：ユーザーの不安を軽減するか、ユーザーのコントロールを高めますか？
3. シンプルさ：これが最もシンプルな解決策ですか？
4. 測定可能性：成功を測定できますか？
5. 障害モード：どのような障害が起こり得ますか？致命的な結果を招く場合は、安全対策を追加してください。
6. 復旧：ユーザーはエラーから復旧できますか？

ユーザーにとっての成果を一文で説明できない場合は、まだ実装しないでください。

コードの原則

巧妙さより明快さ

// ✅ DO: Name for humans reading at 2am
const userAuthenticationStatus = checkAuth(userId);
const formattedOrderDate = formatDate(order.createdAt);

// ❌ DON'T: Clever but obscure
const x = chk(u);
const d = fmt(o.c);

コメントでは「何を」ではなく「なぜ」を説明します。注意すべき言い回し：「ただ」「単に」「明らかに」。

明示的なエラー処理

// ✅ DO: Error states as return types
type Result<T> = 
  | { success: true; data: T } 
  | { success: false; error: UserFacingError };

async function fetchUser(id: string): Promise<Result<User>> {
  try {
    const user = await api.getUser(id);
    return { success: true, data: user };
  } catch (error) {
    return { 
      success: false, 
      error: { 
        message: "Unable to load user profile",
        action: "Please try again or contact support"
      }
    };
  }
}

// ❌ NEVER: Generic errors or silent failures
throw new Error("Something went wrong");

ネットワークの回復性

// ✅ DO: Exponential backoff with jitter
const retryWithBackoff = async <T>(
  fn: () => Promise<T>, 
  maxRetries = 3
): Promise<T> => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      const delay = Math.min(1000 * 2 ** i + Math.random() * 1000, 10000);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  throw new Error('Max retries exceeded');
};

// ✅ DO: Timeout promises
const withTimeout = <T>(promise: Promise<T>, ms: number): Promise<T> =>
  Promise.race([
    promise,
    new Promise<never>((_, reject) =>
      setTimeout(() => reject(new Error('Request timeout')), ms)
    )
  ]);

パフォーマンス予算

コーディングを始める前に、次の基準を設定します。

指標	予算
コールドスタート	平均的なデバイスで < 2s
操作への応答	体感で < 100ms
アニメーション	1フレームあたり < 16ms（60fps）
API 呼び出し（p95）	< 500ms

パフォーマンスの低下は P0 のバグとして扱います。ローエンドデバイスでプロファイリングしてください。

UI コンポーネントの状態

すべてのインタラクティブなコンポーネントは、次のすべての状態に対応する必要があります。

✅ Default (idle)
✅ Hover (pointer devices)
✅ Active/pressed
✅ Focus (keyboard navigation)
✅ Disabled (with explanation why)
✅ Loading (with progress indication)
✅ Error (with recovery action)
✅ Success (with next step)
✅ Empty (with helpful onboarding)

ビジュアルシステム

余白（8pt グリッド）

4px:  Tight grouping (icon + label)
8px:  Related items (form fields in group)
16px: Section separation
24px: Component boundaries
32px: Major sections
48px: Screen-level padding

タイポグラフィのスケール

H1: 32-40px, bold, line-height 1.2
H2: 24-28px, semibold, line-height 1.3
H3: 20-24px, semibold, line-height 1.4
Body: 16-18px, regular, line-height 1.5
Caption: 14px, regular, line-height 1.4

RULE: Never below 14px for body text (accessibility)

モーション

目的	時間	イージング
マイクロインタラクション	100-200ms	ease-out
画面遷移	300-400ms	ease-in-out
読み込み状態	600ms+	linear

ルール：

• アニメーションは説明のために使い、装飾として使わない
• prefers-reduced-motion を尊重する
• ユーザーの操作を遅らせない

アクセシビリティ要件

必須チェックリスト：

• ARIA ラベルを備えたセマンティック HTML
• すべての操作でキーボードナビゲーションが可能
• 色のコントラスト：最低 4.5:1（本文テキストは 7:1）
• タッチターゲット：最低 44x44pt
• スクリーンリーダーでテスト済み
• prefers-reduced-motion を尊重
• prefers-color-scheme を尊重

信頼のアーキテクチャ

すべての機能について、次の質問に答える必要があります。

1. 収集するデータ：どのようなデータか？（収集は最小限に）
2. 障害モード：何が問題になり得るか？（まず障害を想定して設計）
3. 信頼のシグナル：安全性をどう証明するか？（見える形にする）
4. 取り消し可能性：ユーザーは元に戻せるか？（確定前にプレビュー）
5. データの扱い：ユーザーのデータはどうなるか？（利用規約ではなく明示する）

プライバシーのデフォルト設定

// ✅ DO: Default private, opt-in sharing
const defaultSettings = {
  shareAnalytics: false,
  publicProfile: false,
  dataRetention: 'minimum'
};

// ✅ DO: Redact PII in logs
logger.info('user_action', {
  action: 'profile_update',
  userId: hashUserId(user.id), // Never raw PII
  duration_ms: 234,
  success: true
});

フォームの検証

• キー入力のたびではなく、フォーカスが外れたときに検証する
• エラーはフィールドの近くにインラインで表示する
• エラーが発生してもユーザーの入力を保持する（決して消去しない）
• 長いフォームでは下書きを自動保存する
• 無効な場合にのみ送信を無効にし、その理由を説明する

フィードバックループ

ユーザーのすべての操作に応答を返す必要があります。

種類	タイミング	例
即時	< 100ms	ボタンを押したときの視覚的な反応
進行状況	1s を超える処理	読み込みインジケーター
完了	成功後	次の手順とともに「保存しました」と表示
失敗	エラー発生時	起きたことと、その解決方法

エラーメッセージでユーザーを責めないでください。

アンチパターン

コードのアンチパターン（絶対にしない）

❌ Magic numbers without constants
❌ Functions over 50 lines
❌ God objects over 300 lines
❌ Mutable global state
❌ Side effects not in function name
❌ Catching errors without handling
❌ Copy-pasted code

UX のアンチパターン（絶対にしない）

❌ Forced account creation before value
❌ Dark patterns (hidden costs, trick questions)
❌ Generic error messages ("Error 500")
❌ Modal dialogs for everything
❌ Destroying data without confirmation
❌ Disabling paste in password fields
❌ Auto-playing video/audio
❌ Infinite scroll without pagination option

セキュリティチェックリスト

• すべてのユーザー入力をサニタイズする（XSS 対策）
• パラメーター化クエリを使用する（SQL インジェクション対策）
• すべてのエンドポイントにレート制限を適用する
• 状態を変更する操作に CSRF トークンを使用する
• PII を保存時に暗号化する（AES-256）
• すべてのネットワーク通信に TLS 1.3 を使用する
• bcrypt/Argon2 でパスワードをハッシュ化する
• HttpOnly、Secure、SameSite Cookie を使用する

品質ゲート（リリース前）

• Lighthouse スコア > 90
• 重大または高リスクのセキュリティ脆弱性がゼロ
• 主要なフローがオフラインで動作するか、適切に機能を縮退する
• キーボードナビゲーションが動作する
• スクリーンリーダーでテスト済み（VoiceOver + NVDA）
• エラー状態をテスト済み
• 想定ピークの 2 倍の負荷でテスト済み
• 実機のモバイルデバイスでテスト済み
• プライバシーレビューを完了済み
• ロールバック手順を文書化済み

最終指針

すべてのコードは、誰かの生活を測定可能なほど良くするものでなければなりません。

• ユーザーにとっての利点を説明できないなら、リリースしないでください
• 成果を測定できないなら、計測できるようにしてください
• 保守できないなら、シンプルにしてください
• 必然性を感じられないなら、設計し直してください

品質に妥協は許されません。近道ではなく、明確さによってスピードを実現します。