design-polish

デザインのブラッシュアップ（Flutter）

Flutter モバイルアプリの画面をブラッシュアップし、視覚的な階層、読みやすさ、セクションの明確さを改善して、ユーザーがアプリの使い方をすぐに把握できるようにします。作業には明確な方針があり、根拠に基づいて範囲を限定します。各ラウンドは、自己評価ではなく、独立した評価者の判定で締めくくります。

セットアップ

ユーザーが画面を指定していない場合は、次のように尋ねます。

• 「どの画面をブラッシュアップしますか？ルート名（例：/settings、/profile）または lib/ 配下のコンポーネントファイルのパスを指定してください。」

アプリは Android エミュレーターで実行されている必要があります。android-emulator スキル（android-emulator）を使用してください。このワークフローでのスクリーンショット、タップ、スワイプ、アクセシビリティツリーのダンプはすべて、このスキルを通して行います。

scripts/emu.sh health        # confirm device, AVD, foreground app
scripts/emu.sh boot          # if not running
scripts/emu.sh run           # build & install in background
scripts/emu.sh wait-run      # block until attached

デザインのトーンを確立する

画面に手を加える前に、一度だけ実施してください。 これを省略すると、一貫性が失われやすくなります。個々の変更は単独ではよく見えても、アプリのほかの画面と並べると違和感が生じます。

1. 参考画面を見つけます。 次の順に探してください。
   • ユーザーが洗練された画面を指定した場合（「設定画面が素晴らしいので、残りもそれに合わせてブラッシュアップしてください」など）は、その画面を使用します。
   • ホーム画面：lib/main.dart またはルーター設定（GoRouter、AutoRoute など）にある MaterialApp.home、initialRoute、または BottomNavigationBar の最初のタブを確認します。
   • home_page.dart、home_screen.dart、dashboard.dart という名前のファイルを探します。
2. ソースを読みます。 画面のウィジェットファイルと、lib/theme/、lib/widgets/、カスタムの ThemeExtension からインポートされているファイルをすべて開きます。ColorScheme、TextTheme、スペーシング定数、角丸の値、共通レイアウトのプリミティブを確認します。
3. エミュレーターでスクリーンショットを撮ります。 必要に応じて tap-label で画面に移動し、scripts/emu.sh screenshot を実行して、出力されたパスを確認します。スクロールし、各状態を撮影します。
4. デザインのトーンを、具体的な箇条書き 3〜5 項目で記述します。 このアプリの画面を、一般的な Material のデフォルトではなく「このアプリらしく」感じさせる要素をまとめます。参考画面を実際に特徴づけている軸を選び、望ましい姿ではなく、そこにある要素を記述してください。
   • 雰囲気 — 例：落ち着いた／抑制的、遊び心のある／活気に満ちた、大胆な／アーケード風、柔らかな／居心地のよい、レトロ、ネオン。
   • フォント — 使用しているフォントファミリーとウェイト、それぞれの適用箇所。リストを固定します。
   • 色 — ColorScheme 全体の特徴：抑制された配色か表現豊かな配色か、フラットかグラデーションか、彩度のレベル、セマンティックトークン、ThemeExtension の有無。
   • サーフェス — カードの背景、境界線、角丸、エレベーション／シャドウ、ぼかし。
   • 階層を示す要素 — 重要度をどのように示すか：ウェイト、色、スペーシング、境界線、アクセント、イラスト、またはそれらの組み合わせ。
   • モーション — なし、控えめな Material のデフォルト、または表現豊かな動き（カスタムカーブ、ヒーロートランジション、Lottie／Rive）。

確信を持ってトーンを確立できない場合 — 明確な参考画面がない、候補の画面が未完成に見える、コードベース内でテーマに一貫性がないなどの場合は、作業を止めて開発者に尋ねてください。

「コードベースから明確なデザイントーンを特定できませんでした。洗練された参考画面（ファイルパスまたはルート名）を教えていただけますか？既存のスタイルとの一貫性を保つために必要です。」

トーンを確立するまでは作業を進めないでください。ブラッシュアップのワークフローは、目指す方向が分かっている場合にのみ機能します。

ブランドとデザインシステム

上で確立したデザインのトーンを指針にしてください。コードベースから具体的な制約を把握し、それに従ってください。

フォント。 theme.textTheme で使用されているファミリーを特定してください（多くの場合、google_fonts、flutter_fonts、または pubspec.yaml 内のアセットにバンドルされた .ttf で確認できます）。新しいフォントは追加しないでください。タイポグラフィのトークンが不足している場合（例：未使用の labelSmall）、ThemeData 経由で設定し、一貫して適用してください。インラインの TextStyle(...) リテラルは使用しないでください。

色。 既存の ColorScheme トークンを使用してください。ThemeExtension 経由で、新しいセマンティックトークン（例：success、warning）を最大2つ追加できます。追加したトークンは、このセッションで変更するすべての画面に適用してください。ウィジェット全体に単発の16進数リテラルを散在させないでください。

コンポーネント。 既存のカスタムウィジェットが lib/widgets/ または lib/components/ にあれば、それを再利用してください。Material ベースのアプリでは、独自に作成するより SDK ウィジェット（FilledButton、Card、ListTile など）を優先してください。強力なカスタムウィジェットライブラリを持つアプリ（ゲームやブランド色の強いユーティリティアプリによく見られます）では、場違いに見える標準 Material ウィジェットを導入せず、既存のパターンに合わせてください。小規模なユーティリティパッケージの利用は問題ありません。仕上げの段階で新しいコンポーネントライブラリを導入しないでください。

間隔と角丸。 既存の間隔スケール（多くの場合、lib/theme/ 内の Spacing 拡張または EdgeInsets 定数）と角丸の値を特定してください。どちらも変更しないでください。個々の選択に妥当性があっても、ここにばらつきがあると目に不統一に映ります。

ワークフロー（画面ごと）

1. 観察

android-emulator スキルを使って画面を操作してください。

• scripts/emu.sh ui-list — 操作可能な要素を調べます。スクリーンショットを撮るより、こちらを優先してください。
• scripts/emu.sh tap-label "..." — 対象の画面に移動します。
• scripts/emu.sh screenshot — 初期状態をキャプチャします。表示されたパスを確認してください。
• スクロール（swipe）、タブを開く、パネルを展開する、ダイアログを閉じる（tap-label "Close"）など、実際のユーザーのように操作してください。意味のある各状態でスクリーンショットを撮ってください。
• 画面のウィジェットのソースと、その画面が構成に使用する共有ウィジェットをすべて読んでください。

2. 問題の診断

具体的な問題を3～7個書き出してください。それぞれで、該当するウィジェットを特定し、何が問題なのかを述べてください。

• 「TabBarView と横の Drawer がどちらも surfaceContainer を使っているため、両者の境界が視覚的に分かりません。」
• 「本文のテキストがすべて bodyMedium かつ FontWeight.w400 になっており、主要データとラベルを区別できません。」

次のような内容は認められません。「コントラストがもっと必要」「ごちゃごちゃしている感じがする」。

3. 修正

全面的な書き換えではなく、対象を絞ったウィジェットの変更で Dart ソースを編集してください。一度にすべてを変更せず、階層、間隔、色の強調の順に、一度に1つの懸念事項に取り組んでください。

編集を論理的なまとまりごとに終えるたびに、再接続してスクリーンショットを撮り、確認してください。

scripts/emu.sh kill-run && scripts/emu.sh run && scripts/emu.sh wait-run
scripts/emu.sh screenshot

視覚的な変更だけを素早く反復する場合は、ユーザーに自身のターミナルで flutter run を継続してもらい（保存時に IDE からホットリロード）、スクリーンショットだけを撮るようにしてください。安全な既定の方法は、実行を終了して再度実行する方法ですが、1回あたり30～60秒かかります。

変更の見た目がよくない場合は、元に戻して別の方法を試してください。うまくいっていない方向性に修正を重ねないでください。

4. 評価する（サブエージェント）

「変更後」のスクリーンショットを撮影します（ページを再度操作してください）。次に、Agent ツールを使い、最新の Opus モデルで評価担当のサブエージェントを起動し、次のプロンプトを渡します（SCREEN_NAME と NAVIGATION_HINT を埋めてください）。

---

評価担当へのプロンプト：

あなたは、今回の変更を行ったエージェントとは一切関係のない独立したデザイン評価者です。懐疑的で、要求水準の高い批評家として振る舞ってください。Flutter モバイルアプリの画面を評価します。

アプリはすでに Android エミュレーター上で実行されています。操作には android-emulator スキルを使ってください。

• scripts/emu.sh ui-list を実行して、操作可能な項目を確認する
• scripts/emu.sh tap-label "..." を実行して、SCREEN_NAME に移動する（NAVIGATION_HINT）
• scripts/emu.sh screenshot を実行して各状態を撮影する — 表示されたパスを確認する
• スクロールし、すべてのタブをタップし、パネルを展開し、メニューを開くなど、実際のユーザーのように操作してください。意味のある状態ごとにスクリーンショットを撮影してください。

各評価基準を1～10点で採点し、2～3文で根拠を説明してください。

デザイン品質（高ウェイト）： 全体に一貫性がありますか、それとも要素を寄せ集めただけですか？ 色、タイポグラフィ、レイアウト、余白が組み合わさり、独自の雰囲気とアイデンティティを生み出していますか？

独創性（高ウェイト）： 意図的なカスタムデザインですか、それとも Material のデフォルトや AI らしいパターンに頼っていますか？ AI スロップの兆候（きらめき／✨アイコン、「AI 搭載」／「魔法」のバッジ、意味のない装飾的なグラフ、ほかのビジュアル言語に合わない装飾要素）があれば、自動的に不合格です。

仕上がり（中ウェイト）： タイポグラフィの階層、余白の一貫性、色の調和、コントラスト、配置。基本的な品質の確認項目です。ここで不合格なら、基礎が破綻しています。

機能性（中ウェイト）： ユーザーは操作を見つけ、迷わずタスクを完了し、インターフェースを理解できますか？ タップ領域は48dp以上ですか？ テキストはデバイスの DPI で読みやすいですか？

評価の目安：9～10点＝Apple Design Award クラス、または同カテゴリ（ゲームならゲーム、ユーティリティならユーティリティ）で App Store のトップチャートに入るアプリに匹敵し、ほとんど付けません。7～8点＝プロとして十分な品質で、特に指摘なし。5～6点＝ありきたりで、Material のデフォルトコンポーネントを使っており、独自性がありません。3～4点＝明らかな問題があります。1～2点＝壊れています。

7点を超える評価を付ける場合は、懐疑的なシニアデザイナーがなお批判する点を1つ挙げてください。挙げられない場合は、評価を下げてください。

残っている問題を、具体的なウィジェットを示して3～5個の箇条書きで批評してください。曖昧な表現は避けてください。続けて判定を示してください。PASS（すべて7点以上）、ITERATE（高ウェイトの項目が1つでも7点未満）、FAIL（5点未満の項目が1つでもある）。

形式：

DESIGN_QUALITY: X/10 — ...
ORIGINALITY: X/10 — ...
CRAFT: X/10 — ...
FUNCTIONALITY: X/10 — ...

CRITIQUE:
- ...

VERDICT: PASS/ITERATE/FAIL

---

5. 判定を受けて対応する

• PASS： 次の画面に進みます。
• ITERATE： 評価担当の批評を新たな診断として扱い、最初から診断し直さないでください。ステップ3（修正）に戻ります。
• FAIL： 「変更前」に戻し、まったく異なるアプローチを試すことを検討してください。
• 画面ごとの評価ラウンドは最大3回です。上限に達したら、最も高い評価を得たバージョンを維持します。

階層を整えるためのツールキット

レイアウトに必要なものを適用してください。すべての画面にすべてを適用する必要はありません。以下は Material 3 のトークンです。Cupertino、カスタムテーマクラス、テーマを大幅に変更したゲームウィジェットライブラリを使用している場合は、アプリに合わせて読み替えてください。

• セクション間の境界線／区切り線（Divider、OutlinedBorder、1px の colorScheme.outlineVariant）。
• 領域間の背景コントラスト（surface、surfaceContainer、surfaceContainerHighest）。
• 重要度を示す文字の太さ／サイズ（titleLarge > titleMedium > bodyMedium > labelSmall）。
• 余白 — 関連する項目は近くに配置（Gap(4)／Gap(8)）、関連しない項目は離して配置（Gap(24)／Gap(32)）。
• 意味を伝える色 — 主要なアクションには primary を使用し、目立たせない要素には onSurfaceVariant を使用します。
• 主要なカードの左側のアクセント（Container の装飾内で、Border(left: BorderSide(color: primary)) を2～3pxに設定）。
• タブインジケーター — TabBar のアクティブ状態が明確にわかるようにします。非アクティブ状態は unselectedLabelColor で目立たなくします。

アンチパターン

Tone-relative — 確立されたトーンから逸脱している（オリジナリティスコア ≤ 4）

画面をAI生成っぽく見せる最も手っ取り早い方法は、このアプリに合わない視覚要素を追加することです。グラデーション、アニメーション、ヒーローイラスト、装飾的なぼかし、StadiumBorder のピル型、カスタムスクロールバー、パーティクルエフェクト、視差効果、Lottie――どれも適切な文脈では有効な選択ですが、場違いな文脈ではただのノイズです。基準にすべきなのは、上で確立したデザインのトーンであり、固定された美的指針ではありません。

原則：確立されたトーンに含まれていない視覚要素を導入しないこと。 既存のものに合わせてください。アプリ全体がフラットなら、グラデーションを追加しないでください。アプリ全体が落ち着いた雰囲気なら、パーティクルを派手に散らさないでください。アプリ全体でアウトライン付きカードを使っているなら、グラスモーフィックなぼかしレイヤーを導入しないでください。

トーンそのものに問題があると思うなら、それは仕上げのタスクではありません。ユーザーに伝えてください。アプリにないトーンに寄せて磨き上げると、画面が別のアプリのように感じられてしまいます。

あらゆる状況で避けるべき兆候（どれか1つでも該当すればオリジナリティスコア2）

以下は、ゲーム、ユーティリティ、生産性向上アプリなど、どのような文脈でも余計なノイズになります。

1. キラキラ／✨アイコン、「AI搭載」「魔法」「スマート」のバッジ、または装飾として使われるその他のアプリ内AIブランディング
2. 実データを表していない、意味のない装飾用チャート、スパークライン、ゲージ、グラフ
3. 内部的な矛盾――それ以外はフラットなデザインに装飾的な影を付ける、全体が浮き上がったレイアウトにフラットなパネルを貼り付ける、すべてが矩形のアプリで画面ひとつだけ何もかも角丸にする
4. 実際の非同期処理による待機がないのに使うShimmer／スケルトンローダー
5. ユーザーが毎日開く画面に紛れ込ませる「おかえりなさい！」の挨拶、ヒーローバナー、オンボーディング風のヘッダー
6. 機能の変更――ルートの再構成、機能の削除、ウィジェットAPIの変更（仕上げの範囲外です。黙って変更せず、問題として伝えてください）

違和感を見極める質問

• 「Apple Design Awardを受賞した同カテゴリのアプリのデザイナーなら、これを装飾的なノイズだと思うだろうか？」
• 「これをスクロール中に見た人は、AI生成っぽいと思うだろうか？」

どちらかの答えが「はい」なら、元に戻してください。

注意点

• ThemeData とホットリロードは常に連動するとは限りません。 ThemeData、ColorScheme、TextTheme の編集はホットリロードで反映されないことが多く、完全に再起動するまでウィジェットに古い色やタイポグラフィが表示される場合があります。テーマの変更が「反映されない」ときは、編集内容をデバッグする前に、終了して再実行するサイクルを行ってください。
• google_fonts は何も通知せずフォールバックします。 ネットワークに接続されていない場合やビルドキャッシュが空の場合、google_fonts はシステムのデフォルトフォントに置き換えるため、タイポグラフィがありきたりに見えます。フォントの変更後にテキストが急におかしく見えたら、デバイスがネットワークに接続されていることを確認してから再ビルドし、その後に調整してください。
• ステータスバーの表示要素が変更前後の差分に影響します。 キャプチャごとに時刻、バッテリー、通知アイコンが異なります。ステータスバーではなくアプリの表示領域を比較し、変更を評価するときはステータスバーのピクセルを無視してください。
• 「一貫性がない」と感じる原因は、たいていインラインのTextStyle(...)です。 画面のトーンがずれていると感じたら、テーマに手を入れる前に、ウィジェット内のインラインTextStyle、Color(0x...)、ハードコードされたEdgeInsetsのリテラルを探してください。テーマに問題はなく、ウィジェットがテーマを迂回していることがよくあります。

プロセスのルール

• 一度に作業する画面は1つだけです。次に進む前に、全サイクル（観察 → 診断 → 修正 → 評価）を完了してください。
• 新しいColorSchemeまたはTextThemeのトークンは、このセッションで作業するすべての画面に適用してください。特定の画面だけに適用して不整合を残してはいけません。
• 共通ウィジェットやThemeExtensionは、一度修正したうえで、それらを使用するすべての画面を再キャプチャして波及範囲を確認してください。
• 各画面の変更後にdart format .とflutter analyze（またはfvm flutter analyze）を実行してください。評価に進む前にLintの指摘を修正してください。実際の問題が見つかることもよくあります。
• 画面の作業完了を宣言する前にflutter testを実行してください。変更したテキストや構造をウィジェットテストが参照している可能性があります。