Ta UI Polish

Visual Polish Skill

"The last 10% of polish takes 90% of the time – but it's worth it."

When to Use This Skill

Use when:

• Finalizing visual presentation
• Creating UI elements and HUD
• Adding feedback animations
• Implementing transitions

Polish Checklist

Core Visuals

• Lighting is balanced - No blown highlights, no crushed shadows
• Colors match GDD palette - Consistent art direction
• Materials look correct - PBR values appropriate for materials
• Silhouette is readable - Objects identifiable from outline
• Framing guides the eye - Important elements draw attention

Animation & Feedback

• Buttons have hover states - Visual feedback on interaction
• Transitions are smooth - No jarring cuts
• Loading states exist - User knows something is happening
• Error states are clear - Problems are visible and understandable
• Success feedback exists - Positive reinforcement
• Connection status visible - Multiplayer shows network state

Connection Status UI Pattern (Multiplayer)

CRITICAL for multiplayer games: Players need to see connection state and network quality.

States to Indicate

Ping Quality Color Coding

function PingIndicator({ ping }: { ping: number }) {
  const getPingColor = (ping: number) => {
    if (ping < 50) return '#22c55e';  // Green
    if (ping < 100) return '#eab308'; // Yellow
    return '#ef4444';                  // Red
  };

  const getPingStatus = (ping: number) => {
    if (ping < 50) return 'Excellent';
    if (ping < 100) return 'Fair';
    return 'Poor';
  };

  return (
    <div className="ping-indicator" style={{ color: getPingColor(ping) }}>
      <WifiIcon className={`animate-pulse ${ping > 100 ? 'animate-ping' : ''}`} />
      <span>{ping}ms</span>
      <span className="status">{getPingStatus(ping)}</span>
    </div>
  );
}

Implementation Example

// ConnectionStatus.tsx
import { useEffect, useState } from 'react';
import { useConnectionStore } from '@/store/connectionStore';

export function ConnectionStatus() {
  const { connected, connecting, roomId } = useConnectionStore();
  const [ping, setPing] = useState(0);

  // Measure ping every second
  useEffect(() => {
    if (!connected) return;

    const interval = setInterval(async () => {
      const start = performance.now();
      // Send ping to server and await response
      await fetch('/api/ping');
      setPing(Math.round(performance.now() - start));
    }, 1000);

    return () => clearInterval(interval);
  }, [connected]);

  if (connecting) {
    return (
      <div className="connection-status connecting">
        <Spinner className="animate-spin" />
        <span>Connecting...</span>
      </div>
    );
  }

  if (!connected) {
    return (
      <div className="connection-status disconnected">
        <XIcon className="animate-pulse" />
        <span>Disconnected</span>
      </div>
    );
  }

  const pingColor = ping < 50 ? 'green' : ping < 100 ? 'yellow' : 'red';

  return (
    <div className="connection-status connected">
      <CheckIcon className="text-green-500" />
      <span>Connected</span>
      <span className={`ping ping-${pingColor}`}>{ping}ms</span>
    </div>
  );
}

Placement in HUD

┌─────────────────────────────────────────────────────┐
│                              [Connection: ● 45ms] │
│  Health: 100█████████████                           │
│  Armor:  50█████                                    │
│                                  [Alive: 42/64]     │
└─────────────────────────────────────────────────────┘

Icon Patterns

UI Presentation

• Typography is readable - Appropriate sizes, weights, line heights
• Contrast meets accessibility - WCAG AA minimum (4.5:1 for text)
• Spacing is consistent - Grid/spacing system used
• Alignment is intentional - Elements line up properly
• Hierarchy is clear - Most important elements stand out

Performance Polish

• No visible frame drops - 60 FPS maintained
• Loading times are acceptable - Assets optimized
• Memory usage is stable - No leaks or growing allocation
• Mobile tested - Works on target mobile devices

UI Component Polish Template

import { useState } from 'react';
import { html } from '@react-three/drei';
import { motion, AnimatePresence } from 'framer-motion';

interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary' | 'danger';
  disabled?: boolean;
  loading?: boolean;
}

export function PolishedButton({
  label,
  onClick,
  variant = 'primary',
  disabled = false,
  loading = false,
}: ButtonProps) {
  const [isHovered, setIsHovered] = useState(false);

  const baseStyles = {
    padding: '12px 24px',
    borderRadius: '8px',
    fontWeight: 600,
    fontSize: '16px',
    border: 'none',
    cursor: disabled ? 'not-allowed' : 'pointer',
    transition: 'all 0.2s ease',
    opacity: disabled ? 0.5 : 1,
  };

  const variantStyles = {
    primary: {
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      color: 'white',
      boxShadow: isHovered ? '0 8px 20px rgba(102, 126, 234, 0.4)' : '0 4px 10px rgba(102, 126, 234, 0.3)',
      transform: isHovered ? 'translateY(-2px)' : 'translateY(0)',
    },
    secondary: {
      background: 'white',
      color: '#667eea',
      border: '2px solid #667eea',
      boxShadow: isHovered ? '0 4px 15px rgba(102, 126, 234, 0.2)' : 'none',
    },
    danger: {
      background: 'linear-gradient(135deg, #f093fb 0%, #f5576c 100%)',
      color: 'white',
      boxShadow: isHovered ? '0 8px 20px rgba(245, 87, 108, 0.4)' : '0 4px 10px rgba(245, 87, 108, 0.3)',
    },
  };

  return (
    <motion.button
      style={{ ...baseStyles, ...variantStyles[variant] }}
      => setIsHovered(true)}
      => setIsHovered(false)}
      && !loading ? onClick : undefined}
      whileTap={{ scale: disabled || loading ? 1 : 0.95 }}
      disabled={disabled || loading}
    >
      <AnimatePresence mode="wait">
        {loading ? (
          <motion.span
            key="loading"
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
          >
            <LoadingSpinner />
          </motion.span>
        ) : (
          <motion.span
            key="label"
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
          >
            {label}
          </motion.span>
        )}
      </AnimatePresence>
    </motion.button>
  );
}

Visual Feedback Patterns

Hover Feedback

<mesh
  => {
    e.object.scale.setScalar(1.1);
    document.body.style.cursor = 'pointer';
  }}
  => {
    e.object.scale.setScalar(1.0);
    document.body.style.cursor = 'default';
  }}
>
  <boxGeometry />
  <meshStandardMaterial color="orange" />
</mesh>

Click Feedback

function InteractiveMesh() {
  const meshRef = useRef<THREE.Mesh>(null);

  const handleClick = () => {
    // Scale animation
    if (meshRef.current) {
      gsap.to(meshRef.current.scale, {
        x: 1.2,
        y: 1.2,
        z: 1.2,
        duration: 0.1,
        yoyo: true,
        repeat: 1,
      });
    }
  };

  return (
    <mesh ref={meshRef}
      <sphereGeometry />
      <meshStandardMaterial color="blue" />
    </mesh>
  );
}

Progress Feedback

function ProgressBar({ progress }: { progress: number }) {
  return (
    <div className="progress-container">
      <div
        className="progress-bar"
        style={{
          width: `${Math.min(100, Math.max(0, progress * 100))}%`,
          transition: 'width 0.3s ease',
        }}
      />
    </div>
  );
}

Color Guidelines

Accessible Color Combinations

Common Mistakes

• ❌ Red/green as only differentiators (colorblindness)
• ❌ Light text on light background
• ❌ Pure colors (#FF0000, #00FF00) - too harsh
• ❌ Too many colors in one view

Typography Guidelines

/* Font scale - modular scale */
.text-xs { font-size: 0.75rem; }    /* 12px */
.text-sm { font-size: 0.875rem; }   /* 14px */
.text-base { font-size: 1rem; }     /* 16px */
.text-lg { font-size: 1.125rem; }   /* 18px */
.text-xl { font-size: 1.25rem; }    /* 20px */
.text-2xl { font-size: 1.5rem; }    /* 24px */
.text-3xl { font-size: 1.875rem; }  /* 30px */
.text-4xl { font-size: 2.25rem; }   /* 36px */

/* Weights */
.font-light { font-weight: 300; }
.font-normal { font-weight: 400; }
.font-medium { font-weight: 500; }
.font-semibold { font-weight: 600; }
.font-bold { font-weight: 700; }

Spacing System

/* 8px base unit */
.space-1 { padding: 0.25rem; }  /* 4px */
.space-2 { padding: 0.5rem; }   /* 8px */
.space-3 { padding: 0.75rem; }  /* 12px */
.space-4 { padding: 1rem; }     /* 16px */
.space-5 { padding: 1.25rem; }  /* 20px */
.space-6 { padding: 1.5rem; }   /* 24px */
.space-8 { padding: 2rem; }     /* 32px */
.space-10 { padding: 2.5rem; }  /* 40px */
.space-12 { padding: 3rem; }    /* 48px */

Anti-Patterns

❌ DON'T:

• Use placeholder colors (magenta, lime green)
• Skip hover states on interactive elements
• Use too many fonts (>2 typefaces)
• Inconsistent spacing
• No feedback for user actions
• Text on busy backgrounds without contrast

✅ DO:

• Use colors from GDD palette
• Provide visual feedback for all interactions
• Limit fonts to 1-2 typefaces
• Follow spacing system consistently
• Test for color blindness
• Ensure text readability

Checklist

Before considering visual polish complete:

• All interactive elements have hover/click states
• Loading states exist for async operations
• Error messages are clear and actionable
• Success feedback is provided
• Colors meet accessibility standards
• Typography is consistent and readable
• Spacing follows system
• Transitions are smooth (200-300ms)
• Performance tested on target devices
• Visual style matches GDD

Related Skills

For post-processing polish: Skill("ta-vfx-postfx")

Phaser UI Animation Patterns (feat-027)

Lesson from feat-027 (Star Rating Preview): Phaser UI animations use tweens with real-time data updates.

Real-time UI Updates Pattern

// src/ui/HUD.ts - Star rating preview with live score tracking
export class HUD extends Phaser.GameObjects.Container {
  private stars: Phaser.GameObjects.Image[] = [];
  private currentScore: number = 0;

  updateStarRating(score: number, level: number): void {
    // Calculate thresholds per DEC-004: 2-star = 32,000 + (level × 2,000)
    const twoStarThreshold = 32000 + (level * 2000);
    const threeStarThreshold = 66000 + (level * 6000);

    // Determine star count from current score
    const starCount = this.calculateStarCount(score, twoStarThreshold, threeStarThreshold);

    // Update each star's visual state
    for (let i = 0; i < 3; i++) {
      const shouldFill = i < starCount;
      this.updateStarFill(this.stars[i], shouldFill);
    }
  }

  private updateStarFill(star: Phaser.GameObjects.Image, shouldFill: boolean): void {
    const targetColor = shouldFill ? 0xffcc00 : 0xcccccc; // Yellow or gray
    const targetAlpha = shouldFill ? 1.0 : 0.3;

    // Smooth tween for color interpolation
    this.scene.tweens.add({
      targets: star,
      duration: 300,
      ease: Phaser.Math.Easing.Quadratic.Out,
      props: {
        tint: targetColor,
        alpha: targetAlpha,
        scale: shouldFill ? 1.1 : 1.0 // Subtle pulse on fill
      },
      yoyo: false,
      repeat: 0
    });
  }
}

Key Animation Best Practices

Performance Considerations

1. Batch tween updates - Don't create tweens on every frame

   // WRONG - Tweens on every update call
   update() {
     this.star.setFillStyle(this.getColor(score)); // Creates new tween each frame
   }
   
   // RIGHT - Only tween on state change
   private lastStarCount: number = -1;
   update() {
     const newCount = this.calculateStars(score);
     if (newCount !== this.lastStarCount) {
       this.animateStarChange(newCount); // Only tween when changed
       this.lastStarCount = newCount;
     }
   }
   

2. Reuse tween targets - Destroy old tweens before creating new ones

   // Prevent tween accumulation
   updateStarFill(star: Phaser.GameObjects.Image): void {
     // Kill existing tweens on this object
     this.scene.tweens.killTweensOf(star);
   
     // Create new tween
     this.scene.tweens.add({
       targets: star,
       // ... config
     });
   }
   

3. Use appropriate easing for UI

   • Quadratic.Out - Fast start, smooth end (good for fills)
   • Cubic.Out - Smooth throughout (good for transitions)
   • Sine.easeInOut - Gentle in/out (good for pulses)
   • Back.Out - Subtle overshoot (good for button clicks)

External References

• WCAG Color Contrast
• Type Scale Calculator
• Easing functions - Motion.dev - Official Framer Motion easing documentation
• The Easing Blueprint - Reuben Rapose - Comprehensive easing guide for Framer Motion
• Creating Metallic Effect with CSS - CSS gradients for metallic buttons

Professional Game UI Design System (Added: ui-001 Playtest Findings)

Learned from ui-001 playtest: Current UI lacked professional polish. This section documents patterns for shipping-quality game UI.

16:9 Aspect Ratio Enforcement

Pattern: All UI screens must maintain 16:9 aspect ratio, centered on screen with letterbox bars for other ratios.

// src/components/ui/AspectContainer.tsx
const ASPECT_RATIO = 16 / 9;

export function AspectContainer({ children }: { children: React.ReactNode }) {
  return (
    <div className="fixed inset-0 z-10 flex items-center justify-center bg-black">
      <div
        className="relative overflow-hidden"
        style={{
          aspectRatio: ASPECT_RATIO,
          maxWidth: '100vw',
          maxHeight: '100vh',
          width: 'min(100vw, 100vh * 16/9)',
          height: 'min(100vh, 100vw * 9/16)',
        }}
      >
        {children}
      </div>
    </div>
  );
}

Letterbox CSS:

/* Letterbox bars for non-16:9 displays */
.ui-letterbox-top,
.ui-letterbox-bottom {
  position: fixed;
  left: 0; right: 0;
  height: calc((100vh - (100vw * 9 / 16)) / 2);
  background: #000;
  z-index: 50;
}
.ui-letterbox-top { top: 0; }
.ui-letterbox-bottom { bottom: 0; }

@media (min-aspect-ratio: 16/9) {
  .ui-letterbox-top, .ui-letterbox-bottom { display: none; }
}

Adaptive Scaling Tokens

// src/components/ui/tokens.ts
export const UIScale = {
  base: { width: 1920, height: 1080 },

  getScaleFactor(windowWidth: number, windowHeight: number): number {
    const baseWidth = 1920;
    const scale = Math.min(
      windowWidth / baseWidth,
      windowHeight / (baseWidth * 9 / 16)
    );
    return Math.max(0.5, Math.min(2, scale));
  },

  fontSize: {
    xs: '14px',   // 0.875rem
    sm: '16px',   // 1rem
    base: '18px', // 1.125rem
    lg: '24px',   // 1.5rem
    xl: '32px',   // 2rem
    '2xl': '48px', // 3rem
    '3xl': '64px', // 4rem
    display: '128px', // 8rem
  },
};

Metallic Button Design System

Inspired by: Quake III Arena, modern Call of Duty, Overwatch

// Metallic gradient backgrounds
const metallicBackgrounds = {
  primary: `linear-gradient(180deg,
    rgba(249, 115, 22, 0.1) 0%,
    rgba(0, 0, 0, 0.9) 20%,
    rgba(0, 0, 0, 1) 50%,
    rgba(0, 0, 0, 0.9) 80%,
    rgba(249, 115, 22, 0.1) 100%
  )`,

  secondary: `linear-gradient(180deg,
    rgba(38, 38, 38, 0.9) 0%,
    rgba(10, 10, 10, 1) 50%,
    rgba(38, 38, 38, 0.9) 100%
  )`,
};

// Hover glow effects
const metallicGlow = {
  hover: `box-shadow:
    0 0 20px rgba(251, 115, 22, 0.4),
    inset 0 0 20px rgba(251, 115, 22, 0.1)`,

  active: `box-shadow:
    0 0 40px rgba(251, 115, 22, 0.6),
    inset 0 0 30px rgba(251, 115, 22, 0.2)`,
};

Custom Easing Curves for Game UI

Sources: Motion.dev Easing, The Easing Blueprint

// Easing curve library for game UI
export const GameEasing = {
  // Snappy entrance (menu reveal)
  snap: [0.22, 1, 0.36, 1] as const,

  // Smooth reveal (screen transitions)
  reveal: [0.16, 1, 0.3, 1] as const,

  // Elastic bounce (button release)
  bounce: [0.34, 1.56, 0.64, 1] as const,

  // Weighty press (button click)
  press: [0.4, 0, 0.2, 1] as const,
};

// Animation timing specifications
const buttonAnimations = {
  idleEnter: { duration: 400, ease: GameEasing.snap },
  hover: { duration: 150, ease: GameEasing.press },
  active: { duration: 50, ease: GameEasing.press },
  release: { duration: 300, ease: GameEasing.bounce },
};

Gaming Typography

/* Import Google Fonts for game UI */
@import url('https://fonts.googleapis.com/css2?family=Orbitron:wght@700;900&family=Rajdhani:wght@500;600;700&display=swap');

:root {
  --font-display: 'Orbitron', 'Impact', sans-serif;
  --font-ui: 'Rajdhani', 'Segoe UI', sans-serif;
  --font-mono: 'JetBrains Mono', 'Courier New', monospace;
}

Industrial Color Palette

:root {
  /* Primary - Electric Orange (Quake-inspired) */
  --color-primary-500: #f97316;
  --color-primary-600: #ea580c;

  /* Secondary - Cyan/Blue */
  --color-secondary-500: #06b6d4;

  /* Metallic Grays */
  --color-metal-900: #0a0a0a;
  --color-metal-700: #262626;
  --color-metal-500: #525252;

  /* Surface Colors */
  --color-surface-bg: rgba(10, 10, 10, 0.95);
  --color-surface-border: rgba(251, 115, 22, 0.3);

  /* Glow Effects */
  --color-glow-primary: rgba(249, 115, 22, 0.6);
}

UI Design System Checklist

Before considering UI polished:

• 16:9 Enforcement - All screens maintain aspect ratio
• Adaptive Scaling - UI scales to any window size
• Design Tokens - Colors, typography, spacing systematized
• Metallic Buttons - Industrial styling with gradients
• Custom Easing - Game-appropriate animation curves
• Gaming Fonts - Orbitron/Rajdhani or similar
• Hover Glow - Visual feedback on interaction
• Sound Feedback - Optional but recommended
• 60+ FPS - Animations maintain performance
• E2E Tests - Visual regression tests pass

Converted and distributed by TomeVault — claim your Tome and manage your conversions.