/flame-harness-design

name: flame-harness-design
description: Phase 3 — define the Flutter design_tokens.dart spec (palette, typography, spacing), the game's art/visual concept, and the asset/audio sourcing plan.
argument-hint: ""
allowed-tools: [Agent, Read, Write, Edit, Bash]

flame-harness-design

Phase 3 of the flutter-flame-harness pipeline. Reads the latest PRD and `config.md`, then produces a design document that specifies the `lib/ui/design_tokens.dart` constants, the game's visual/art concept, and the asset and audio sourcing plan (including launcher icon and splash screen intent). Advances pipeline state to `contract`.

All file schemas (`config.md`, `state.md`, `pipeline-log.md`) and the phase transition table are defined in `docs/harness-protocol.md` — refer to that document as the single source of truth (§2 for `state.md` schema; §7 for the `design → contract` transition). Do not redefine schemas here.

---

Input

1. Read `docs/harness/config.md`

Extract:

| Key | Use | |---|---| | `app_idea` | Informs visual tone (action vs. casual vs. puzzle) | | `app_name` | Used in splash screen heading and icon badge | | `app_slug` | Used to derive asset directory naming conventions | | `default_language` | The user's conversation language; write copy samples in it |

If `config.md` does not exist, abort with: `flame-harness-design: docs/harness/config.md not found — run the orchestrator to bootstrap first.`

2. Read the latest PRD

Find the most recent file matching `docs/harness/plans/*-prd.md` (sort descending by filename, take the first). If no PRD exists, abort with: `flame-harness-design: no PRD found in docs/harness/plans/ — run flame-harness-plan first.`

Extract from the PRD:

• **Genre & core mechanic** — informs colour mood (e.g., dark sci-fi vs. bright hyper-casual)
• **Target age / tone** — age rating and energy level of the visual style
• **Monetisation hook** — AdMob placement type (banner at bottom → affects HUD spacing)
• **Win/lose conditions** — informs what UI states need distinct visual treatment

---

Design tokens

Write a specification for `lib/ui/design_tokens.dart` that a generator phase Claude can implement verbatim as `const` Dart values. The spec must cover every sub-section below.

Colour palette

Derive a palette from the genre and tone. Use the following template — replace every `<...>` with a real hex colour and rationale:

Primary       <#RRGGBB>  — main brand / call-to-action colour
PrimaryDark   <#RRGGBB>  — pressed / shadow state of primary
Accent        <#RRGGBB>  — highlights, score text, power-up glows
Background    <#RRGGBB>  — game canvas and screen background
Surface       <#RRGGBB>  — card, dialog, overlay background
OnBackground  <#RRGGBB>  — text / icon colour on background
OnSurface     <#RRGGBB>  — text / icon colour on surface
Error         <#RRGGBB>  — error states, health loss flash

Rules:

• Minimum contrast ratio of 4.5:1 for any text colour against its background.
• Background and Primary must share the same temperature (both warm or both cool).
• Accent must differ from Primary by at least 60° of hue to provide visual pop.
• For dark-themed games (sci-fi, horror) set Background ≤ `#333333`; for bright

hyper-casual games set Background ≥ `#E0E0E0`.

Typography scale

Specify font family, weight, and size for each role. If the game uses a custom font, name the Google Font and its import path; otherwise default to `Roboto`.

Display   family: <FontName>  weight: 900  size: 48 sp  — game title on main menu
Heading1  family: <FontName>  weight: 700  size: 32 sp  — screen headings
Heading2  family: <FontName>  weight: 700  size: 24 sp  — section headings, score
Body      family: <FontName>  weight: 400  size: 16 sp  — general UI text
Caption   family: <FontName>  weight: 400  size: 12 sp  — labels, tooltips
Button    family: <FontName>  weight: 600  size: 18 sp  — primary buttons
HUD       family: <FontName>  weight: 700  size: 20 sp  — in-game HUD counters

Use `sp` (Flutter `TextScaler`-aware) for all sizes. Game HUD text should use `fontFeatures: [FontFeature.tabularFigures()]` for score counters.

Spacing scale

Define a base unit and derive the full spacing scale. Typical base is 4 dp:

xs:   4 dp   — tight padding (icon labels)
sm:   8 dp   — inner card padding
md:  16 dp   — standard screen margin
lg:  24 dp   — section gap
xl:  32 dp   — screen top/bottom padding
xxl: 48 dp   — hero area padding

All layout constants in `design_tokens.dart` use these named values — no raw numbers in UI code. Spacing values are applied as `const double` fields.

Also define `minTapTarget = 48.0` (dp) — every menu/overlay button must be at least this size (accessibility gate R10; pairs with the 4.5:1 contrast rule above).

Radius and elevation

radiusSm:   4 dp   — chip, small badge
radiusMd:   8 dp   — card, dialog
radiusLg:  16 dp   — bottom sheet, hero card
radiusFull: 999 dp — pill buttons

elevationSurface:  2 dp
elevationDialog:   8 dp
elevationFab:     12 dp

`design_tokens.dart` file template

The generator must emit a file with this exact structure:

// lib/ui/design_tokens.dart
// AUTO-GENERATED by flame-harness-design — do not edit manually.
// See docs/harness/plans/<date>-design.md for rationale.

import 'package:flutter/material.dart';

abstract class DesignTokens {
  // --- Colours ---
  static const Color primary       = Color(0xFF______);
  static const Color primaryDark   = Color(0xFF______);
  static const Color accent        = Color(0xFF______);
  static const Color background    = Color(0xFF______);
  static const Color surface       = Color(0xFF______);
  static const Color onBackground  = Color(0xFF______);
  static const Color onSurface     = Color(0xFF______);
  static const Color error         = Color(0xFF______);

  // --- Spacing ---
  static const double spaceXs  =  4;
  static const double spaceSm  =  8;
  static const double spaceMd  = 16;
  static const