unreal-engine-mcp-system-plugin/UI_WORKFLOW.md

# UI_WORKFLOW — UMG/Slate UI authoring guide for AI agents

> **READ THIS BEFORE EDITING ANY `WBP_*` / UMG / SLATE / UI.**
> If you start a UI task without following this file, you will produce a generic
> placeholder ("prototype look"). This document is the contract that turns
> "ugly UMG demo" into "shippable UI".

## 0. Quick decision flow

```
user asks for UI work
  │
  ├─ Is there a DA_UITheme asset in /Game/UI/Theme/ ?  ── no ─→ STEP A. Build theme first.
  │                                                         (one-time setup, ~5 min)
  ├─ Are there base components in /Game/UI/Components/ ? ── no ─→ STEP B. Build component library.
  │
  ├─ Did the user give a reference image / mood / brand?  ── no ─→ STEP C. Ask for one before coding.
  │
  └─ All three present? ─→ STEP D. Compose screen → screenshot → iterate.
```

You **must not** invent palettes, spacing, or component shapes on the fly. If
a token is missing, you ADD it to the theme. If a component is missing, you
CREATE it in the library. The screen WBP only composes.

---

## STEP A — The Theme (one DataAsset to rule them all)

### A.1 Class
Create C++ DataAsset `UProjectUITheme : UPrimaryDataAsset` (use `cpp_scaffold_op`):

```cpp
USTRUCT(BlueprintType) struct FProjectUIPalette {
    GENERATED_BODY()
    UPROPERTY(EditAnywhere) FLinearColor Primary    = FLinearColor::White;
    UPROPERTY(EditAnywhere) FLinearColor Accent     = FLinearColor(1, 0.5, 0.1, 1);
    UPROPERTY(EditAnywhere) FLinearColor Danger     = FLinearColor::Red;
    UPROPERTY(EditAnywhere) FLinearColor Surface    = FLinearColor(0.05, 0.05, 0.05, 1);
    UPROPERTY(EditAnywhere) FLinearColor SurfaceAlt = FLinearColor(0.1, 0.1, 0.1, 1);
    UPROPERTY(EditAnywhere) FLinearColor Ink        = FLinearColor(0.9, 0.9, 0.85, 1);
    UPROPERTY(EditAnywhere) FLinearColor Muted      = FLinearColor(0.5, 0.5, 0.45, 1);
};

USTRUCT(BlueprintType) struct FProjectUIType {
    GENERATED_BODY()
    UPROPERTY(EditAnywhere) FSlateFontInfo H1;     // 48pt display
    UPROPERTY(EditAnywhere) FSlateFontInfo H2;     // 32pt headings
    UPROPERTY(EditAnywhere) FSlateFontInfo Body;   // 16pt text
    UPROPERTY(EditAnywhere) FSlateFontInfo Caption;// 12pt small
    UPROPERTY(EditAnywhere) FSlateFontInfo Mono;   // monospace / terminal text
};

UCLASS()
class PROJECTUI_API UProjectUITheme : public UPrimaryDataAsset {
    GENERATED_BODY()
public:
    UPROPERTY(EditAnywhere, Category="Theme") FProjectUIPalette Palette;
    UPROPERTY(EditAnywhere, Category="Theme") FProjectUIType    Type;
    // Spacing rhythm — use index, not raw px.
    UPROPERTY(EditAnywhere, Category="Theme") TArray<float> Spacing = {4, 8, 12, 16, 24, 32, 48, 64};
    UPROPERTY(EditAnywhere, Category="Theme") float CornerRadius = 4.f;
    UPROPERTY(EditAnywhere, Category="Theme") float BorderWeight = 1.f;
    // Named brushes — referenced by their FName key from WBPs.
    UPROPERTY(EditAnywhere, Category="Theme") TMap<FName, FSlateBrush> Brushes;
};
```

### A.2 Instance
Create instance at `/Game/UI/Theme/DA_UITheme` (one per visual mode — fork as
`DA_UITheme_<Mode>` if a project needs several). Example tuning:

| Token | Value | Why |
|---|---|---|
| Palette.Surface | `(0.04, 0.05, 0.05, 1)` | near-black base |
| Palette.SurfaceAlt | `(0.09, 0.1, 0.09, 1)` | row striping |
| Palette.Ink | `(0.87, 0.91, 0.83, 1)` | off-white, never pure | 
| Palette.Accent | `(0.95, 0.62, 0.21, 1)` | amber highlight |
| Palette.Danger | `(0.78, 0.10, 0.10, 1)` | muted red, not hex red |
| Palette.Muted | `(0.45, 0.50, 0.45, 1)` | green-grey |
| Type.H1 | font `Roboto Mono Bold`, 48, letter spacing +1 | display |
| Type.Body | font `Inter Regular`, 16 | readable body |
| CornerRadius | 0 | sharp / brutalist |
| BorderWeight | 1.5 | thicker → more readable |

### A.3 Access
Every WBP holds `UPROPERTY(EditDefaultsOnly) UProjectUITheme* Theme;` set in Class
Defaults to `DA_UITheme`. No hardcoded colors anywhere. If you catch yourself
typing `FLinearColor(0.7, 0.1, 0.1, 1)` — stop, add a token to the theme instead.

---

## STEP B — Component Library

Build these once, reuse forever. All under `/Game/UI/Components/`.

### Required base set
| Component | Purpose | Variants |
|---|---|---|
| `WBP_Button` | All clickable | Primary, Ghost, Danger, Icon-only |
| `WBP_Card` | Container w/ header/body/footer | Flat, Raised, Outlined |
| `WBP_HUDPanel` | Framed panel (corner brackets, overlay channel) | Top, Bottom, Floating |
| `WBP_StatBar` | Numeric stat bar (health/energy/progress) | Horizontal, Vertical, Circular |
| `WBP_Label` | Text wrapper that auto-picks Type token | H1, H2, Body, Caption, Mono |
| `WBP_Divider` | 1px line | Solid, Dashed, Glitchy |
| `WBP_Icon` | Wraps `Image` with theme tint | size=spacing token |
| `WBP_ListRow` | One row of a list, themed | Selected/Hovered states wired |
| `WBP_Modal` | Centered overlay with backdrop | Confirm, Form, Info |
| `WBP_Toast` | Bottom-slide notification | Info, Warn, Error |

### Authoring rules
- **No hardcoded sizes** — use `Theme->Spacing[idx]` (e.g. padding = `Spacing[3]` = 16px).
- **Every interactive widget has 4 states wired**: Normal, Hovered, Pressed, Disabled. Hooked from theme brushes, not duplicated.
- **Each component exposes `SetVariant(EVariant)` and `SetState(EState)` BP-callable funcs** — so the screen WBP composes by setting flags, not by hand-tweaking child widgets.
- **Animation:** every state transition has a 80-150ms ease. Define one `WidgetAnimation` per state in `WBP_Button`, copy pattern to others. No animation = feels dead.

### Optional stylized overlays
- `WBP_HUDPanel` can expose a Niagara/Material overlay channel — bind project-specific material instances (e.g. `MI_UI_Scanline`, `MI_UI_Noise`) as defaults if your project has them.
- `WBP_Label` Mono variant can use a chromatic-aberration material instance.
- Background of every HUD piece: prefer a themed `MI_UI_Surface` material over a flat solid color when a stylized look is wanted.

---

## STEP C — Reference parsing protocol

When user supplies a reference image, **do not** start coding. First emit:

```
REFERENCE TOKENS
================
Palette (6 colors HEX, ordered by dominance):
  1. Primary surface:   #__
  2. Surface alt:       #__
  3. Ink (text):        #__
  4. Accent:            #__
  5. Danger/warning:    #__
  6. Muted/secondary:   #__

Typography:
  H1 size:  __pt   weight: __   tracking: __
  Body size:__pt   weight: __
  Family hint: __ (serif/sans/mono/condensed)

Spacing rhythm (3 visible gaps in px): __  __  __
  → suggested Spacing array: [__, __, __, __, __, __, __, __]

Corner radius observed: __px  (0 = sharp / brutalist)
Border weight observed: __px

Visual hierarchy (one sentence): __

Mood (3 adjectives): __, __, __

Departures from current DA_UITheme:
  - Theme.Palette.__ should become #__ (was #__)
  - Theme.Spacing[__] should become __ (was __)
```

Then ask the user: "apply to existing theme or fork as `DA_UITheme_<NewName>`?"

Once approved, use `audio_op set_property` / direct asset edits to mutate the
theme DataAsset. Never edit individual WBPs to match a ref — change the theme,
all WBPs follow.

---

## STEP D — The Vision Loop (most important)

This is what makes AI UI not suck. After ANY structural change, you MUST:

```
1. widget_op apply_tree / set_property / ... (your edit)
2. widget_op compile_save {bp_path}
3. widget_op screenshot {bp_path, size: [1920, 1080]}
4. Read the returned png_path. If you are a vision-capable model:
   open the file, look at the result, list 3 specific problems before next edit.
5. Loop until no problems remain.
```

### Hard rule
- **Maximum 2 blind edits** (without screenshot) per session. After that, MUST screenshot. If a user reports "it looks bad", your first action is `widget_op screenshot`, not asking for clarification.
- **Before declaring "done"**, last action MUST be a screenshot, and you MUST describe what you see (not what you intended).
- The screenshot landing path is `<Project>/Saved/MCP/widgets/<bp_name>.png`. Always attach this to your turn output.

### What to look for in the screenshot
- **Alignment grid** — are baselines and gutters consistent? Use a mental 8px grid.
- **Hierarchy** — can you ID primary action in <1s by squinting?
- **Density** — is it crammed (Unity-tutorial vibe) or breathing?
- **Color count** — is anything outside the theme palette? If yes, that's a bug.
- **Edge cases** — empty list, longest possible label (16 chars), worst-case localization (German is +30%).

---

## STEP E — Screen composition

When user asks for a new screen (`WBP_MainMenu`, `WBP_HUD_InGame`, ...):

1. Sketch hierarchy in text first:
   ```
   WBP_MainMenu (RootCanvas)
     WBP_HUDPanel "title-bar" (anchored top, span)
       WBP_Label H1 "GAME TITLE"
     WBP_Card "menu-list" (centered, 480x600)
       WBP_Button Primary "Continue"
       WBP_Button Ghost   "New Game"
       WBP_Button Ghost   "Settings"
       WBP_Button Danger  "Quit"
     WBP_Label Caption "v0.4.2  •  Build 2026-05-28" (bottom-left)
   ```
2. Confirm with user (one screen = one confirmation step, not per widget).
3. Build with `widget_op apply_tree` (single transaction, single undo).
4. Compile + screenshot.
5. Iterate per Step D loop.

---

## Naming & paths (enforced)

| Asset | Path | Naming |
|---|---|---|
| Theme DataAsset | `/Game/UI/Theme/` | `DA_UITheme_*` |
| Base components | `/Game/UI/Components/` | `WBP_<Name>` |
| Screens | `/Game/UI/Screens/` | `WBP_<Screen>` (no prefix like "Menu_" — flat) |
| Materials | `/Game/UI/Materials/` | `M_UI_*`, `MI_UI_*` |
| Icons | `/Game/UI/Icons/` | `T_UI_Icon_<verb>_<noun>` |
| Frame brushes | `/Game/UI/Frames/` | `T_UI_Frame_*` |

If asked to create UI assets outside these paths, ask why. Probably a mistake.

---

## Things NEVER to do (anti-patterns AI agents fall into)

1. ❌ Hardcoded color `FLinearColor(0.2, 0.2, 0.2)` anywhere. → Use theme.
2. ❌ Hardcoded padding `Padding=8`. → Use `Theme->Spacing[1]`.
3. ❌ One giant CanvasPanel screen with absolute coords for everything. → Use HorizontalBox/VerticalBox/Grid composition.
4. ❌ "Just add a `Border` widget" for a card. → Use `WBP_Card` component.
5. ❌ Per-screen unique button styling. → Add a variant to `WBP_Button`.
6. ❌ Default UE font (Roboto). → Always pick from `Theme->Type`.
7. ❌ Default `Button` widget visible to the user. → Always wrap in `WBP_Button` because state animations live there.
8. ❌ Skip Step D. → If you didn't screenshot, you didn't finish.
9. ❌ Generate icons inline as text "≡" or "✕". → Use `WBP_Icon` with a real Texture2D.

---

## Required first action for any UI session

```
discover_op find_bp_by_parent { parent_class_path: "/Script/ProjectUI.ProjectUITheme" }
```
- 0 hits → STEP A (build theme).
- 1+ hits → fetch the `DA_UITheme` palette via `validation_op get_references` or read directly, cache token names in your working memory.

```
discover_op find_bp_by_parent { parent_class_path: "/Script/UMG.UserWidget" }
```
List existing components. If `/Game/UI/Components/WBP_Button` missing → STEP B.

Then and only then proceed to the user's actual request.

---

## Why this works

Without this guide, AI generates UMG by sampling "what UMG typically looks like
on GitHub" — boring, generic, grey. With this guide:

- **Decisions are constrained** (theme tokens, component variants) → no more "AI inventing aesthetics from scratch every time".
- **Composition replaces design** → LLMs are great at composing; bad at painting.
- **Vision loop closes the feedback gap** → AI sees its output, judges it, fixes it.
- **References parse to data**, not vibes → reproducible, debuggable, diffable.

Result: shippable UI in 1-2 iterations instead of 15.