flutter-custom-design-system

Flutter カスタムデザインシステム

標準の Material／Cupertino のスキルセットを安易に使うのは適切ではありません。このリポジトリですでに色、書体、角丸、モーション、または押下可能なコンポーネントに名前が付いている場合は、その名前と値を使ってください。ユーザーからシステムを捨てるように求められていない限り、アプリのスタイルを FilledButton ／ NavigationBar ／ ColorScheme.fromSeed に寄せて変更しないでください。

関連スキル：flutter-native-ui — 実際に Material 3 または Cupertino の外観を求めるアプリに限って使います。

参考資料

references/
  tokens.md      ThemeExtension mount, context accessor, 1:1 rule
  pressable.md   Scale/sink press, NoSplash, focus ring, semantics

まずデザインシステムを確認する

ウィジェットを記述する前に、リポジトリを検索して次の項目を確認してください。

• ThemeExtension<
• 色やトークンを返す extension <Name> on BuildContext
• *tokens*、*semantics*、*theme*、WIDGETS.md、DESIGN-SYSTEM.md という名前のファイル
• *Pressable という名前のウィジェット
• NoSplash.splashFactory ／ splashFactory: NoSplash

次に、近くにある本番画面を開き、そのアクセサー（context.pt、St6Theme.of(context)、context.colors など）を使ってください。プロダクトコードでは、新しいアクセサーではなく、そのアクセサーを使う必要があります。

まだシステムがなく、ユーザーがシステムを求めている場合は、references/tokens.md と references/pressable.md にあるパターンを導入してください。トークンモジュールは1つ、拡張機能は1つ、押下可能なコンポーネントは1つにします。サードパーティの UI キットは追加しないでください。

厳守事項

トークン

• 値は1つのソース（Dart のトークンファイル、CSS／JSON から生成したもの、または承認済みの tokens.dart）にまとめます。ウィジェットに生の16進カラー値、場当たり的な角丸、独自に決めた時間を記述してはいけません。
• 実行時には ThemeData.extensions の ThemeExtension<T> と、単一のコンテキストアクセサーを使って適用します。拡張機能と並べて、無関係なウィジェットから FooColors クラスをインポートしてはいけません。
• システムファイルと1対1で対応させます。引き継ぎ資料に #C9A24B とある場合、トークンも #C9A24B にします。コントラストを「改善」したり、ライトテーマを考案したり、システムにない役割を追加したりしてはいけません。
• 役割が不足している場合は、トークンソースと拡張機能の両方に追加するか、確認してください。近道としてウィジェットに #hex を直接記述してはいけません。
• ダークモードを使うのは、システムに含まれている場合だけです。ダークパレットを考案してはいけません。

外観

• アプリが Flutter Material のデフォルトだと、ひと目でわかってしまうような見た目にしてはいけません。システムで指定されている場合を除き、インクリップル、M3 のプライマリコンテナのピル、標準の NavigationBar インジケーターを使ってはいけません。
• すべてのタップは、アプリ共通の Pressable を経由させます（リポジトリになければ作成してください）。押下時は、縮小および／または沈み込みの動きを付けます。テーマと Pressable の両方で splashFactory: NoSplash.splashFactory と透明なオーバーレイを設定します。
• 「アクセシビリティを手軽に得る」ために、ブランド独自のコントロールを FilledButton ／ ElevatedButton ／ InkWell で囲み、後からスプラッシュに対処することは避けてください。セマンティクスは Pressable に設定します。
• Material の動作（フォーカス、メディアクエリ、テキストスケーラー、Shortcuts）は使っても、Material の外観は使いません。

書体と余白

• 書体の役割はシステム（または拡張機能のテキストスタイル）に従います。システムが TextTheme に対応付けていない限り、TextTheme.of(context).titleLarge を使ってはいけません。
• 余白、角丸、モーションにはトークンの値（space200、radiusControl、durationPress）を使います。EdgeInsets.all(13) や Duration(milliseconds: 180) のような値を呼び出し側で独自に考案してはいけません。

キーとデバッグ

• インタラクティブなコントロールには const ValueKey<String>('kebab-name') を使い、テストから find.byKey で検索できるようにします。
• 神モード、ギャラリー、事前入力、ジャンプチップは kDebugMode でのみ有効にし、実際の認証／セッション経路を通します。本番リリースで使える抜け道を作ってはいけません。

禁止事項

• システムにフォントがすでに含まれている場合は、google_fonts を追加しないでください。ゴールデンテストが重要な場合は、FontLoader でそのフォントを読み込みます。Roboto のゴールデンテストはプロダクトそのものではありません。
• flutter_screenutil、GetX、または2つ目のデザインパッケージを追加しないでください。
• ブランド独自のサーフェスに、標準の M3 コンポーネントを「今回だけ」と混在させないでください。

画面を構築する

1. トークンファイル、拡張機能、押下可能ウィジェット、既存の画面を1つ確認します。
2. 新しい AppBar と NavigationBar を組み合わせるのではなく、プロジェクトのシェル（カスタムのアプリバー／タブバー）を使って足場を作ります。
3. 色、文字、余白、角丸、アニメーションには、拡張機能／トークンだけを使います。
4. タップ操作には標準の押下可能ウィジェットを使います。アイコンにはシステムのアイコンセットを使い、システムで採用されていない限り Icons.favorite は使いません。
5. セーフエリアとキーボードには、コンテンツに SafeArea を使い、MediaQuery.sizeOf ／ viewInsetsOf ／ textScalerOf を使用します。システムで定義されている場合はウィンドウ幅のブレークポイントを使い、定義されていない場合は既存のシェルのルールに従います。
6. プロジェクトのアナライザーと、実行中の画面で検証します。

Material のデフォルト設定を使わない場合

システムのウィジェット一覧に記載されていない場合、ブランドを表す画面では次のものを使わないでください。

FilledButton、NavigationBar、NavigationRail、NavigationDrawer、SnackBar（システムにトーストがある場合）、FloatingActionButton、Chip、エレベーションの色合いを適用した Material、デフォルトのスプラッシュ効果を持つ InkWell。

OS 標準の操作要素で、画面の装飾にあたらないものについては、システムで代替要素が指定されていない場合に .adaptive()（Switch.adaptive、Checkbox.adaptive）を使ってもかまいません。

検証する

1. 変更したファイルを grep で検索し、Color(0x ／ Color.from ／ # がないか確認します。該当箇所はウィジェットではなく、トークンファイルに記述します。
2. 新しいタップ対象には、すべて標準の押下可能ウィジェットを使います。
3. アナライザーの警告がないことを確認します。ホットリロードし、実行中の画面を Material 3 のギャラリーの記憶ではなく、近くにあるブランド画面と照らし合わせて確認します。
4. ウィジェットテストでは、キーがある場合は表示テキストではなく find.byKey を使います。