ガバナンス

11-1. 役割と承認

AIエージェントは、既存のコードから規則を推測し、同じ書き方を他の箇所へ広げることがあります。そのため判断の根拠をデザイン仕様書に置き、プロダクトオーナーの承認が必要な変更を明示します。

• プロダクトオーナー
  • 仕様を変える判断を持ち、原則、共通トークン、新しい視覚表現の追加と変更を承認する
  • Pull Requestをレビューし、マージを判断する
• 実装者(人とAIエージェント)
  • UIを変更する前に、デザイン仕様書と関連ガイドを読む
  • 仕様で判断できない点は、プロダクトオーナーへ確認する
  • 自動化していない確認の結果をPull Requestに記録する
• プロダクトオーナーの承認が必要な変更
  • 原則、共通トークン、新しい視覚表現の追加と変更
  • 原則と既存仕様が衝突するときの例外
  • 既存仕様の範囲内での適用には、承認を必要としない

11-2. Source of Truth

要件と判断基準はデザイン仕様書で確認します。確認用カタログは、トークンと実コンポーネントから標本を描画します。

• 記載する内容
  • 採用済みのトークン、部品、パターン、ライティングだけを記載する
• Issueで管理する内容
  • 改善候補、優先度、移行状況
  • そのPull Requestで直さない、実装との差分
• 適合の基準
  • 実装とテストは、デザイン仕様書に記載した要件へ適合させる
• 既存コードの扱い
  • 実装の現在値を、仕様の根拠にしない
  • 仕様と異なる値や表現を見つけたら、同じものを他へ広げない
  • そのPull Requestで直す不一致はPull Requestに、直さない不一致はIssueに記録する

11-3. 適合ルール

実装者が変更を作るときに守るルールです。

• 未定義の視覚表現を先に実装しない
  • 新しい視覚表現はプロダクトオーナーの承認を得る
  • デザイン仕様書で定義してから使用する
• 新しい色を直接追加しない
  • まずsemantic tokenで表せるか確認する
• 記事本文に独自フォントを持ち込まない
  • 見出しはNoto Sans JP、コードはJetBrains Monoを使う
• 同じ役割のカードを別の見た目で増やさない
  • Card primitiveかPost / Scrapbox patternを使う
• ダークテーマを後付けにしない
  • 新しいsurface / text / stateはライトとダークを同時に定義する
• 色だけで操作状態を示さない
  • 背景、太さ、境界、文言、aria stateを併用する
• 動きを必須情報にしない
  • reduced motionでも内容と操作が成立するようにする

11-4. 更新方法

仕様を変更するときは、次の順序で更新します。各手順の主語が、その手順を担う役割です。

1. 実装者が変更理由と適用範囲を決める
2. 承認が必要な変更の場合は、実装者が実装する前にプロダクトオーナーの承認を得る
3. 実装者が、デザイン仕様書に変更後の要件と標準仕様を書く
4. 実装者が、対応する実装、関連ガイド、確認用カタログ、検証を、変更の影響範囲に応じて更新する
5. 実装者が、影響する画面幅、テーマ、入力方法、状態で要件と期待する結果を確認する
6. 自動化していない確認がある場合は、実装者が結果をPull Requestに記録する
7. 実装者がpnpm test:design-systemを実行し、実コンポーネントとの接続を確認する
8. 実装者がpnpm buildを実行し、公開成果物の検査が通ることを確認する
9. プロダクトオーナーがPull Requestをレビューする
10. 仕様・実装・確認の結果が一致している場合は、プロダクトオーナーがマージする