farolero/skills/premium-game-ui/SKILL.md

name, description, license, metadata

name	description	license	metadata
premium-game-ui	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.	Apache-2.0	author version gentleman-programming 1.4

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.
11. Generated frames are decoration, not layout. Never stretch ornate button/card frames as functional backgrounds when they contain rails, gems, or ornaments that can cross text. Keep labels, icons, hit states, disabled states, and alignment in reusable Flutter components; put generated art behind or around them as a non-blocking layer.
12. Preserve scrollability on mobile. Any premium screen with variable content (users, avatars, settings, QR plus lists) must remain inside a SingleChildScrollView or have an explicit bounded internal scroll. Do not remove scroll by introducing full-height Column + Expanded layouts unless the content is guaranteed to fit.
13. QR codes are functional, not decorative. A QR must have a clean white quiet zone, enough padding, and no decorative overlay above the scannable pixels. Frames can sit behind or outside the white QR card, never over finder patterns.
14. Avatars must not be clipped or tiny. Do not place large avatars in ListTile.leading without explicit leading width/height. Use BoxFit.contain for generated avatar art, reserve enough tile height, and prefer visibly useful sizes (roughly 48-96 px in lists/cards, 86-112 px in pickers/previews).
15. Localization is part of premium UI. User-visible copy must go through the app localization system. For Spanish, use Spanish from Spain; avoid Rioplatense/Argentinian phrasing in app strings.
16. Do not bundle chroma-source images. Chroma-key sources are temporary production files. Only the final transparent PNG/WebP and opaque backgrounds belong in registered Flutter asset folders; otherwise green-screen images can be shipped accidentally.
17. Use shared decorative art widgets for repeated phases. Debate, word reveal, voting, host-management, notes, rules, and history screens should reuse generated gameplay art through shared components so layouts stay consistent and text/buttons remain real Flutter widgets.
18. Analyzer cleanliness is mandatory. When editing Dart, do not introduce unused getters/fields or analyzer-only style issues. Avoid (_, __)/(_, __, ___) callback parameters because unnecessary_underscores is enabled; name unused callback parameters descriptively (context, index, error, stackTrace) or use only one _ where valid.
19. Premium buttons must be scalable by construction. Do not place a decorative button PNG over a Flutter button that already has its own shape/background. Either use a true scalable technique (9-slice/centerSlice with protected corners/ornaments) or draw the frame with Flutter CustomPainter. Text, icons, hit state, disabled state, and dynamic width must remain real widgets and must not distort the artwork.
20. Generated backgrounds should not be polluted by procedural placeholders. Once a screen has a real generated atmosphere background, remove temporary CustomPainter silhouettes, confetti rectangles, generic circles, or debug-looking shape layers unless they are intentional premium effects.

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

Stack(
  children: [
    const PremiumBackground(), // opaque generated or painted base
    Positioned.fill(child: Image.asset('assets/ui/generated/shared/screen_atmosphere_bg.webp', 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