| name | moai-ref-ui-polish |
| description | UI polish and interface-completion reference: the small visual details — concentric border radius, optical alignment, shadow-vs-border, motion easing, typography smoothing, tabular numbers, icon stroke weight, hit areas — that separate polished interfaces from generic ones. Agent-extending skill that amplifies frontend/UI domain work with production-grade "interface taste" rules. NOT for: backend logic, database design, DevOps, security audits, non-UI work.
|
| when_to_use | Use for UI polish and design-completion work: building UI components, reviewing frontend code, implementing animations, hover/active states, shadows, borders, typography, icons, micro-interactions, enter/exit animations, or any visual detail work. Amplifies frontend domain work (manager-develop, Agent(general-purpose) with frontend instructions) with interface-design taste rules. Implementation examples are Web/CSS; the design principles are platform-neutral (apply to native mobile/desktop UI too).
|
| user-invocable | false |
| metadata | {"version":"1.0.0","category":"domain","status":"active","updated":"2026-07-28","tags":"ui, polish, design, animation, typography, motion, frontend, reference"} |
| progressive_disclosure | {"enabled":true,"level1_tokens":100,"level2_tokens":3000} |
UI Polish Reference
Target Agents
manager-develop - Applies polish rules during frontend/UI component implementation (cycle_type=tdd or cycle_type=ddd context)/moai review - UI-design review surface; equivalently available as a per-spawn Agent(general-purpose) frontend specialist per archived-agent-rejection.md §C
Core Philosophy
Great interfaces are a collection of small details that compound into a great experience. AI agents frequently miss these details — an ease-in easing on an enter animation (should be ease-out), a solid border where a semi-transparent shadow reads better, or mismatched radii on nested elements. None of these is catastrophic; together they separate "polished" from "generic".
Before suggesting polish changes, identify the project's existing styling system (design tokens, spacing scale, motion library). Never introduce a second styling system for polish fixes — extend the existing one.
Geometry and Alignment
| Principle | Rule | Rationale |
|---|
| Concentric Border Radius | outerRadius = innerRadius + padding | Mismatched radii on nested elements is the most common cause of an interface "feeling off" |
| Optical over Geometric Alignment | When geometric centering looks wrong, align optically | Buttons with icons, play triangles, and asymmetric icons need a manual nudge; geometric center is visually off-center for these shapes |
Elevation and Structure
| Element | Use | Avoid |
|---|
Semi-transparent layered box-shadow | Depth, elevation, floating surfaces | Solid borders for depth (they read heavy and flat) |
| Borders | Structure, dividers, separators, selected/focus state | Using shadows for structural separation (ambiguous) |
Motion
| Pattern | Rule | Common Mistake |
|---|
| Enter animation easing | ease-out (decelerate) — element arrives calmly |
