flutter-ui

/supergraph:flutter-ui

Build pixel-faithful Flutter UI grounded in the project's own design system.

Announce: "🎨 /supergraph:flutter-ui — scanning project design system..."

Input modes

• Figma MCP — user provides a Figma URL or node ID
• Image — user provides a screenshot or design image

Both modes follow the same pipeline.

Figma URL parsing

Extract fileKey and nodeId from the URL before calling any Figma tool:

https://www.figma.com/design/<fileKey>/Title?node-id=<raw-nodeId>

• fileKey — alphanumeric segment after /design/ or /file/
• nodeId — value of node-id query param; replace - with : (e.g. 123-456 → 123:456)

If the user provides only a nodeId string without a URL, use it as-is.

---

Step 1 — Scan project design system

Before reading any Figma or image data, scan src to understand what already exists.

1a. Locate token files

Search for files likely to hold design tokens. Common patterns:

find . -type f -name "*.dart" | xargs grep -l "Color\|Colors\." | grep -iE "color|theme|token|palette|constant|style|dimen|size|spacing|radius" | head -20
find . -type f -name "*.dart" | xargs grep -l "TextStyle\|fontSize\|FontWeight" | grep -iE "text|typo|font|style|theme" | head -20
find . -type f -name "*.dart" | xargs grep -l "EdgeInsets\|Radius\|double" | grep -iE "dimen|size|spacing|padding|radius|constant" | head -20
find . \( -name "theme" -o -name "themes" \) -type d | head -10

1b. Extract token registry

Read the identified files and build a registry. Replace <token_file>, <style_file>, <dimen_file>, <theme_file> with the actual file paths found in Step 1a:

Colors:

grep -n "static.*Color\|Color(" <token_file> | head -40

Extract: constant name → hex/Color value. Example:

AppColors.primary       → Color(0xFF6C63FF)
AppColors.background    → Color(0xFFF5F5F5)

Text styles:

grep -n "TextStyle\|fontSize\|FontWeight\|fontFamily" <style_file> | head -40

Extract: style name → fontSize + fontWeight + color. Example:

AppTextStyles.heading1  → 24sp, FontWeight.w700, AppColors.textPrimary
AppTextStyles.body      → 14sp, FontWeight.w400, AppColors.textSecondary

Spacing / sizing:

grep -n "static.*double\|const.*= [0-9]" <dimen_file> | head -40

Extract: constant name → value. Example:

AppSizes.paddingM  → 16.0
AppSizes.radiusS   → 8.0

Theme setup:

grep -n "ThemeData\|colorScheme\|MaterialApp" <theme_file> | head -20

Determine token access pattern — this governs all generated code:

• Direct class (e.g. AppColors.primary, AppTextStyles.body) → use class references in Step 5
• ThemeData/ColorScheme (e.g. Theme.of(context).colorScheme.primary) → use Theme.of(context) in Step 5; map token names to ColorScheme / TextTheme properties instead of static class fields

If mixed (both patterns exist), note which is dominant and match that.

1c. Find existing reusable widgets

find . -path "*/widgets/*.dart" -o -path "*/components/*.dart" -o -path "*/common/*.dart" | head -30

For each file, extract the widget class name and constructor signature using grep (avoids line-count truncation):

grep -n "class \|const \|required \|this\." <widget_file> | head -20

Read until the constructor closing ) is found. List as:

AppButton(label, onPressed, [variant])    → lib/widgets/app_button.dart
AppCard(child, [padding, elevation])      → lib/widgets/app_card.dart

If no widget files found in any of the search paths: skip reuse — generate all UI sections as new private classes.

1d. Detect state management

grep -rn "import.*bloc\|import.*riverpod\|import.*provider\|import.*get_it\|import.*getx\|import.*mobx\|import.*signals" lib/ pubspec.yaml | head -10

Note the detected pattern (BLoC / Riverpod / Provider / GetX / none). Generated code must match this pattern exactly.

1e. Detect naming & import convention

Pick the first .dart file found under common screen directories as the reference file:

find . \( -path "*/lib/screens/*.dart" -o -path "*/lib/pages/*.dart" -o -path "*/lib/features/*.dart" -o -path "*/lib/views/*.dart" -o -path "*/lib/ui/*.dart" -o -path "*/lib/presentation/*.dart" \) | head -1

If none found, widen to any dart file in lib/:

find lib/ -name "*.dart" | head -1

Then extract import style:

grep -n "import.*lib/" <reference_file> | head -10

Note: barrel exports (index.dart), path aliases, part files. This determines how to write imports in generated code. If still no file found, default to direct path imports (import 'package:<app>/...').

---

Step 2 — Extract design from Figma or image

If Figma MCP:

mcp__Figma__get_figma_data(fileKey=<key>, nodeId=<nodeId>)

From the response, extract:

• Layout: width, height, padding, gap, axis direction (row/column), alignment

• Colors: all fill/stroke hex values → map to registry tokens (Step 1b)

• Text: content, fontSize, fontWeight, fontFamily → map to registry text styles

• Corners: borderRadius values → map to registry sizing constants

• Spacing: padding, margin, gap values → map to registry spacing constants

• Variants / interactive states: if the node has variants (e.g. Normal / Hover / Disabled / Active), note each variant name. Map to a boolean or enum param on the generated widget (e.g. isDisabled, isActive, isSelected). Do not generate separate widgets per variant — use a single widget with conditional styling.

• Images/icons: for each icon/image node, classify:

  • Matches a Material icon name → use Icon(Icons.xxx), no download needed
  • Custom SVG/PNG → note node ID for download

If a Figma color has no match in the token registry: note it, do NOT hard-code — STOP and ask user whether to add a new token or map to the nearest existing one. Resume only after user confirms.

Download custom assets if needed:

mcp__Figma__download_figma_images(fileKey=<key>, nodes=[{nodeId, fileName}], localPath=<assets/path>)

After download, check pubspec.yaml for the flutter.assets: section. If the downloaded path is not declared, add it — otherwise Image.asset(...) will fail at runtime.

If image input:

Analyze the image visually:

• Break down the screen into sections (AppBar, body, cards, buttons, bottom nav, etc.)
• Estimate layout: flex direction, alignment, rough padding/gap
• Identify colors visually → match to nearest token in registry (Step 1b) by visual similarity
• Identify text hierarchy → map to nearest text style in registry
• Identify component shapes → match to existing widgets (Step 1c)
• Identify images/icons → classify as Material icon or custom asset (same as Figma mode)
• For any custom asset referenced: verify its directory is declared under flutter.assets: in pubspec.yaml

If a color has no close match in registry: note it, do NOT hard-code — ask user whether to add a new token or use the nearest existing one.

---

Step 3 — Build token mapping table

Before writing any code, produce a mapping table:

Design value	Token to use	Source
#6C63FF (primary button bg)	AppColors.primary	registry
24px bold heading	AppTextStyles.heading1	registry
16px padding	AppSizes.paddingM	registry
8px corner radius	AppSizes.radiusS	registry
#FFFFFF background	AppColors.background	registry

Unmapped token gate: After building the full table, check for any unmapped row. If found → STOP, present the partial table to user, ask for resolution per value, resume only after all rows are resolved. The per-value STOP in Step 2 is for early discovery during extraction; this gate is the final check before proceeding to Step 4. Do not proceed with any unmapped value.

---

Step 4 — Plan widget tree

Decompose the design into a widget tree before coding:

Scaffold
  AppBar: AppBar(title: Text(..., style: AppTextStyles.heading1))
  body: SingleChildScrollView
    Column(padding: AppSizes.paddingM)
      _HeaderSection          ← new private widget
      SizedBox(h: AppSizes.gapL)
      AppCard(...)            ← existing widget
        _CardContent          ← new private widget
      SizedBox(h: AppSizes.gapM)
      AppButton(...)          ← existing widget

Rules:

• Reuse existing widgets (Step 1c) wherever shape/behavior matches
• Extract sections > 40 lines into private _WidgetName classes in same file
• No widget method extraction (Widget _buildXxx()) — use classes

---

Step 5 — Generate code

Write the Flutter file(s) following these rules:

Token usage (CRITICAL — no exceptions)

// ✅ correct
color: AppColors.primary
fontSize: AppTextStyles.body.fontSize
padding: EdgeInsets.all(AppSizes.paddingM)
borderRadius: BorderRadius.circular(AppSizes.radiusS)

// ❌ forbidden
color: Color(0xFF6C63FF)
fontSize: 14
padding: EdgeInsets.all(16)
borderRadius: BorderRadius.circular(8)

Structure rules

• One file per screen/major component
• File name and location follow the convention detected in Step 1e — match the naming style (login_screen.dart, login_page.dart, login_view.dart) and directory (lib/screens/, lib/pages/, lib/features/xxx/) of existing screens
• Private widgets as classes at bottom of file, not methods
• Import via the convention detected in Step 1e (barrel or direct path)
• const constructors wherever possible
• No print(), no TODO, no placeholder lorem ipsum unless design specifies

Assets

• Material icons → Icon(Icons.xxx) — no asset file needed

• Custom PNG → use flutter_gen generated class (e.g. Assets.images.imgWelcome.image()) — check how existing screens reference images to match the generated class naming

• Custom SVG → use flutter_gen generated class (e.g. Assets.icons.icArrowRight.svg()) — check how existing screens reference SVGs to match the generated class naming

• Asset naming convention (applied when downloading from Figma or referencing existing files):

  • Format: snake_case, all lowercase, no spaces, no hyphens
  • Prefix by type: ic_ for icons, img_ for images, bg_ for backgrounds
  • Include state suffix where relevant: ic_home.svg, ic_home_active.svg, ic_home_disabled.svg
  • No generic names: image1.png, icon.svg, asset.png are forbidden
  • Example: img_onboarding_welcome.png, ic_arrow_right.svg, bg_login.png

• pubspec.yaml asset declaration check: before referencing any asset (downloaded from Figma or existing in project), verify its directory is declared under flutter.assets:. If not, add it before running build_runner.

• If flutter_gen is not in pubspec.yaml: propose setup before writing any asset reference:

  1. Add to pubspec.yaml:

     dev_dependencies:
       build_runner:
       flutter_gen_runner:
     flutter_gen:
       output:
         package_parameter_enabled: false
     flutter:
       assets:
         - assets/images/
         - assets/icons/
     

  2. Run flutter pub get && dart run build_runner build
  3. After the generated Assets class exists, use it in all asset references — never fall back to Image.asset(string) or SvgPicture.asset(string)

Responsive

• If design shows both mobile and tablet/desktop layouts → use LayoutBuilder
• Otherwise assume single form factor — do not add responsive boilerplate speculatively

State

• Use the state management pattern detected in Step 1d — do NOT introduce a different one
• const constructors only for stateless leaf widgets; omit where widget depends on runtime state or reactive data

---

Step 6 — Self-verify before handing off

Run these checks mentally (or with grep) before presenting code:

# Hard-coded hex colors or Color.from* constructors
grep -n "Color(0x\|Color\.from" <generated_file>

# Hard-coded Colors.* named colors (review hits — only Colors.transparent is acceptable)
grep -n "Colors\." <generated_file>

# Hard-coded spacing/size literals
grep -nE "EdgeInsets\.(all|symmetric|only|fromLTRB)\([^A-Z]|SizedBox\((height|width):\s*[0-9]|Container\((height|width):\s*[0-9]|fontSize:\s*[0-9]" <generated_file>

# No Widget method extraction
grep -n "Widget _build" <generated_file>

# Stray debug/placeholder
grep -n "print(\|TODO" <generated_file>

For color hits: Color(0x* and Color.from* → always fix. Colors.* → fix unless it is Colors.transparent. For spacing hits → replace with registry token. If any unfixable hit → note in output and ask user.

---

Output format

Present in this order:

1. Token mapping table (Step 3) — so user can verify before seeing code
2. Widget tree plan (Step 4 summary) — one-paragraph description
3. Generated code — full file(s), ready to paste
4. Assets to download (if any Figma images) — list node IDs + target paths

---

Hard rules

• NEVER hard-code a color, font size, spacing, or radius value
• NEVER introduce a new design token without explicit user approval (user may approve during unmapped-color pause in Step 2/3)
• NEVER use a state management pattern different from what src uses
• NEVER extract widget sections as methods — use private classes
• ALWAYS scan src before reading Figma/image
• ALWAYS produce the token mapping table before code
• If registry is empty (no tokens found): stop and ask user where design tokens are declared before proceeding