---
name: premium-game-ui
description: >
  Create professional, layered, high-impact game screens in Flutter using AI-generated, high-quality transparent art assets without flattening the UI into a single image.
  Trigger: when designing, generating, reviewing, or implementing premium game UI screens, reward screens, medal screens, avatar screens, overlays, transparent assets, visual effects, cinematic game feedback, or mockup-to-Flutter work.
license: Apache-2.0
metadata:
  author: gentleman-programming
  version: "1.1"
---

## When to Use

- A screen must look premium, cinematic, addictive, or game-like.
- Assets are being generated for Flutter UI.
- The user mentions transparent backgrounds, overlays, rewards, medals, avatars, glows, bursts, particles, confetti, Lottie, Rive, or visual polish.
- A prototype/mockup must be converted into real app UI.
- A screen currently looks like plain Flutter plus gradients/glows and needs real art direction.

## Critical Patterns

1. **Never flatten a real screen into one PNG.** Use real Flutter layout for text, buttons, state, progress, localization, accessibility, and responsive behavior.
2. **Do not fake premium art with simple procedural glows.** If the target is cinematic/professional, generate real high-quality raster art assets with the image generation system and integrate them. CustomPainter, gradients, and stock Material icons are support layers, not hero art.
3. **Generate a layered asset kit before coding.** Separate opaque backgrounds from transparent overlays, hero illustrations, frames, badges, buttons, bursts, particles, smoke, and decorative props.
4. **Transparent means technically transparent.** Every overlay/hero/frame/prop that sits above Flutter UI must be PNG/WebP with alpha; image corners should usually be `alpha=0`. Reject white/black baked backgrounds.
5. **High-quality generated assets are mandatory for premium screens.** For each premium screen or lote, create or reuse at least one production-grade generated art asset unless the screen is intentionally text-only.
6. **Right size, not maximum size.** Icons/avatars/medals usually 128-256 px. Hero/foreground illustrations 512-1024 px. Full mobile backgrounds can be 1080x1920 or equivalent.
7. **Use animation by responsibility.**
   - `flutter_animate`: widget entrances, shimmer, scale, blur, staggered UI.
   - `confetti`: short celebrations; keep particles controlled.
   - `Rive`: interactive/stateful vector animation.
   - `Lottie`: After Effects JSON animations.
8. **Avoid expensive composition.** Do not wrap large areas in `Opacity` when a semitransparent color/image or pre-baked alpha asset works.
9. **Plan before generating.** First write the layer list: filename, role, size, alpha requirement, anchor, and Flutter usage.
10. **No placeholders in final premium work.** Generic icons, basic circles, simple radial glows, plain gradients, and procedural sparkles are acceptable only as temporary scaffolding. Replace them with generated art assets before claiming the screen is done.

## Mandatory Image Generation Rule

For premium/cinematic screens, the implementation MUST use generated bitmap assets where visual impact matters.

| Need | Required output |
| --- | --- |
| Full-screen atmosphere | Generated opaque background, usually 1080x1920 or 1440x2560. |
| Hero symbol / mascot / emblem | Generated PNG/WebP with transparent background, usually 512-1024 px. |
| Card/button frame art | Generated PNG/WebP with transparent background and alpha corners. |
| Reward burst / glow / confetti / smoke | Generated PNG/WebP with alpha, corners transparent. |
| Small icon/medal/avatar | Generated or hand-authored asset at 128-256 px, transparent background. |

If an asset needs transparency and the generator cannot emit native alpha, generate it on a flat chroma-key background, remove the key locally, and validate alpha before integration.

## Asset Acceptance Checklist

- [ ] Correct role: background, overlay, hero element, icon, frame, badge, prop, or animation.
- [ ] Correct format: PNG/WebP alpha for pictorial overlays, SVG for simple vector, Rive/Lottie for motion.
- [ ] Correct alpha: overlay corners transparent unless intentionally full-canvas.
- [ ] Generated art quality: looks like polished game art, not a procedural placeholder.
- [ ] Project-bound generated images are copied into `assets/ui/...` or another registered asset directory.
- [ ] Centered visible content; no neighboring sprite fragments.
- [ ] No unnecessary 2048+ px icons.
- [ ] Registered in `pubspec.yaml` only at the needed directory level.
- [ ] Integrated through `Stack`/widgets, not as a full-screen screenshot.
- [ ] Compared against the mockup/prototype; if the result still looks like plain Flutter with glows, it is not done.

## Screen Workflow

1. Define the screen as layers: background, atmosphere, hero, panels, controls, motion.
2. Generate the required high-quality image assets first.
3. Remove/challenge any opaque background on overlays; validate transparent corners.
4. Integrate assets with real Flutter widgets in `Stack`.
5. Compare against the prototype and iterate asset-by-asset.
6. Only then update the screen code and verification notes.

## Flutter Integration Pattern

```dart
Stack(
  children: [
    const PremiumBackground(), // opaque generated or painted base
    Positioned.fill(child: Image.asset('assets/ui/premium/vignette.png', fit: BoxFit.cover)),
    Positioned(top: 80, left: 0, right: 0, child: RewardHero()), // generated transparent hero asset + Flutter text/state
    Positioned.fill(child: IgnorePointer(child: ConfettiWidget(confettiController: controller))),
    SafeArea(child: RealScreenContent()), // text/buttons/progress remain widgets
  ],
)
```

## Documentation

- Main pipeline: `docs/premium_game_ui_pipeline.md`