1---
2name: moai-ref-ui-polish
3description: >
4 UI polish and interface-completion reference: the small visual details — concentric
5 border radius, optical alignment, shadow-vs-border, motion easing, typography
6 smoothing, tabular numbers, icon stroke weight, hit areas — that separate polished
7 interfaces from generic ones. Agent-extending skill that amplifies frontend/UI domain
8 work with production-grade "interface taste" rules.
9 NOT for: backend logic, database design, DevOps, security audits, non-UI work.
10
11when_to_use: >
12 Use for UI polish and design-completion work: building UI components, reviewing
13 frontend code, implementing animations, hover/active states, shadows, borders,
14 typography, icons, micro-interactions, enter/exit animations, or any visual detail
15 work. Amplifies frontend domain work (manager-develop, Agent(general-purpose) with
16 frontend instructions) with interface-design taste rules. Implementation examples are
17 Web/CSS; the design principles are platform-neutral (apply to native mobile/desktop UI too).
18
19user-invocable: false
20metadata:
21 source: https://skillmd.com/skills/modu-ai/moai-ref-ui-polish
22 version: "1.2.0"
23 category: "domain"
24 status: "active"
25 updated: "2026-08-19"
26 tags: "ui, polish, design, animation, typography, motion, frontend, accessibility, audit, reference"
27
28# MoAI Extension: Progressive Disclosure
29progressive_disclosure:
30 enabled: true
31 level1_tokens: 100
32 level2_tokens: 5000
33---
34
35# UI Polish Reference
36
37## Target Agents
38
39- `manager-develop` - Applies polish rules during frontend/UI component implementation (`cycle_type=tdd` or `cycle_type=ddd` context)
40- `/moai review` - UI-design review surface; equivalently available as a per-spawn `Agent(general-purpose)` frontend specialist per `archived-agent-rejection.md` §C
41
42## Core Philosophy
43
44Great 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".
45
46Before 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.
47
48## Geometry and Alignment
49
50| Principle | Rule | Rationale |
51|-----------|------|-----------|
52| Concentric Border Radius | `outerRadius = innerRadius + padding` | Mismatched radii on nested elements is the most common cause of an interface "feeling off" |
53| 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 |
54
55## Elevation and Structure
56
57| Element | Use | Avoid |
58|---------|-----|-------|
59| Semi-transparent layered `box-shadow` | Depth, elevation, floating surfaces | Solid borders for depth (they read heavy and flat) |
60| Borders | Structure, dividers, separators, selected/focus state | Using shadows for structural separation (ambiguous) |
61
62## Motion
63
64| Pattern | Rule | Common Mistake |
65|---------|------|----------------|
66| Enter animation easing | `ease-out` (decelerate) — element arrives calmly | `ease-in` on enter (element appears to slam into place) |
67| Exit animation easing | `ease-in` (accelerates away), mirroring the enter curve (small fixed `translateY`) | Full-height collapse, or harsher-than-enter motion |
68| Interruptible state changes | CSS `transition` (can be interrupted mid-animation) | `keyframes` for interactive states (cannot interrupt) |
69| Staged entrances | Stagger semantic chunks ~100ms — only for infrequent staged entrances | Staggering routine, high-frequency interactions (feels sluggish) |
70| Contextual icon animation | `opacity`/`scale`/`blur` cross-fade (scale 0.25→1, opacity 0→1, blur 4px→0) | Toggling `visibility` (jarring, no transition) |
71| Press feedback | `scale(0.96)` on click — always 0.96 | Smaller than 0.95 (reads as a bug, not a press) |
72| First-render enter | Skip with `initial={false}` on `AnimatePresence` (or equivalent) | Enter animation fires on page load (disorienting) |
73| Motion restraint | No custom animation on high-frequency interactions; motion is never the only feedback channel | Animating everything (noise, performance cost, accessibility) |
74
75### Motion Easing Values (Web/CSS)
76
77| Case | Value |
78|------|-------|
79| With motion library (Framer Motion et al.) | `transition: { type: "spring", duration: 0.3, bounce: 0 }` |
80| Without motion library (CSS) | `cubic-bezier(0.2, 0, 0, 1)` for the standard "decelerate" curve |
81| Never | `transition: all` — always specify exact properties (`transition-property: scale, opacity`) |
82
83### Motion Accessibility and Cost
84
85| Rule | Detail |
86|------|--------|
87| Reduced-motion branch (required) | Every non-decorative animation needs a `prefers-reduced-motion: reduce` path. Vestibular-disorder users are physically harmed by large-displacement and parallax motion. Reduce to an opacity cross-fade or remove the animation — never merely shorten it. The branch is authored at the same time as the animation, not retrofitted |
88| Animate the compositor, not the layout | `transform` and `opacity` are composited and skip layout and most paint. `width`, `height`, `top`, `left`, `margin`, and `padding` trigger layout on every frame (thrashing), which is why the same visual effect janks when driven by the wrong property. Move with `translate`, resize with `scale` |
89
90> Motion principles behind these rules — the three decision passes, motion layers, the
91> 1/3 rules, stagger budgets, personality archetypes, Disney-adapted ranges, and the
92> emotion-to-motion map — live in `references/motion-principles.md` (L3, load on demand
93> when motion is the substance of the work).
94
95## Typography
96
97| Rule | Implementation (Web/CSS) | When |
98|------|--------------------------|------|
99| Font smoothing | `-webkit-font-smoothing: antialiased` on root layout | macOS targets (sharper rendering) |
100| Tabular numbers | `font-variant-numeric: tabular-nums` | Dynamically updating numbers (counters, timers, prices) — prevents layout shift |
101| Heading wrapping | `text-wrap: balance` | Headings (prevents orphan words, evens line lengths) |
102| Body wrapping | `text-wrap: pretty` | Body paragraphs (avoids orphan widows) |
103
104## Imagery
105
106| Rule | Value |
107|------|-------|
108| Image outline | `1px` subtle outline at low opacity |
109| Outline color (light mode) | pure black — `oklch(0 0 0 / 0.1)` |
110| Outline color (dark mode) | pure white — `oklch(1 0 0 / 0.1)` |
111| Never | Tinted neutral outlines (read as a color choice, not a separation cue) |
112
113## Interaction
114
115| Rule | Value |
116|------|-------|
117| Minimum hit area (touch/mobile) | 44 × 44 px |
118| Minimum hit area (dense desktop) | 40 × 40 px (extend with pseudo-element if the visual is smaller) |
119| Hit area overlap | Never let hit areas overlap |
120| Hover on touch (never load-bearing) | `:hover` does not exist on touch — anything reachable only by hover is simply gone on a phone. Keep affordances visible by default and gate hover styling behind `@media (hover: hover) and (pointer: fine)` |
121| Hover on pointer (always present) | The inverse rule: on a pointer device every clickable surface needs a distinct hover state, transitioning over ~100-200ms. A pointer resting on a target with no feedback reads as broken |
122| `will-change` | Only `transform`, `opacity`, `filter` — and only when first-frame stutter is observed; never `will-change: all` |
123
124## Icons
125
126| Rule | Detail |
127|------|--------|
128| Stroke matches text weight | `1.5px` stroke beside regular (400) text; `2px` beside semibold (600) text |
129| One stroke weight per set | Never mix icon libraries in one interface |
130| State via color, not assets | Icons use `currentColor`; states come from CSS `color`/`opacity` — never separate asset files |
131| Outline vs fill | Outline variant is default; fill variant marks the active state |
132
133## Review Modes
134
135| Mode | Coverage | Finding Cap |
136|------|----------|-------------|
137| `quick` | Primary user path, high-traffic states; HIGH/MEDIUM issues only | 5 |
138| `full` | Entire scope across all categories (Typography, Surfaces, Motion, Icons, Interaction) | 15 |
139
140### Severity
141
142| Level | Meaning |
143|-------|---------|
144| HIGH | Makes interaction inaccessible, misleading, unreadable, or repeatedly disruptive |
145| MEDIUM | Noticeable usability or consistency problem |
146| LOW | Isolated polish issue (full mode only) |
147
148### Verdict
149
150| Verdict | Condition |
151|---------|-----------|
152| Block | Any HIGH finding remains |
153| Needs changes | Only MEDIUM or LOW findings remain |
154| Approve | No actionable findings remain |
155
156> Auditing an existing codebase rather than reviewing a diff? `references/design-audit.md`
157> (L3, load on demand) carries the mechanical detection patterns behind the checklists
158> below — motion gaps, accessibility violations, layout-property animation, and the
159> duration/easing inventories that only surface across a whole codebase. It reports into
160> the severity scale and finding caps above, not a separate one.
161
162<!-- moai:evolvable-start id="rationalizations" -->
163## Common Rationalizations
164
165| Rationalization | Reality |
166|---|---|
167| "The framework handles animations correctly by default" | Framework defaults are generic. Easing, timing, and stagger must be specified per interaction, not inherited. |
168| "A solid border is simpler than a layered shadow" | A solid border communicates structure; depth needs transparency. Using a border for elevation reads heavy and flat. |
169| "Geometric centering is correct, optical adjustment is bikeshedding" | Geometric center is visually off for asymmetric shapes (icons, play triangles). Optical alignment is the difference users feel but cannot name. |
170| "Motion is optional polish, the interface works without it" | Motion is feedback. Without it, state changes are ambiguous (did it register?). But motion must be restrained — animating everything is noise. |
171| "Hit area equals visible area" | A 20px icon needs a 44px hit area on touch. Overlapping or undersized hit areas are the most common mobile usability defect. |
172| "`transition: all` is convenient" | It transitions properties you did not intend (layout, color), causing unexpected animation. Always specify exact properties. |
173
174<!-- moai:evolvable-end -->
175
176<!-- moai:evolvable-start id="red-flags" -->
177## Red Flags
178
179- Enter animation uses `ease-in` (should be `ease-out`)
180- Nested elements with mismatched border radii (no concentric relationship)
181- Solid border used for depth/elevation instead of semi-transparent shadow
182- `transition: all` instead of specific properties
183- Hit area smaller than 40×40px, or overlapping hit areas
184- Dynamically updating numbers without `tabular-nums` (layout shifts on each update)
185- Icon stroke weight mismatched with adjacent text weight
186- Separate icon asset files per state instead of `currentColor` recoloring
187- Page-load enter animation fires without a skip (`initial={false}`)
188- `will-change: all`, or `will-change` set permanently instead of only on stutter
189- Animation with no `prefers-reduced-motion` branch (or a branch that only shortens the duration instead of removing the displacement)
190- Movement driven by `top`/`left`/`width`/`height` where a `transform` would do (layout thrashing every frame)
191
192<!-- moai:evolvable-end -->
193
194<!-- moai:evolvable-start id="verification" -->
195## Verification
196
197- [ ] Enter animations decelerate (`ease-out`); exit animations accelerate (`ease-in`), and entrances run longer than exits
198- [ ] Every non-decorative animation has a `prefers-reduced-motion: reduce` branch
199- [ ] Movement uses `transform`/`opacity`, not `width`/`height`/`top`/`left`
200- [ ] Nested elements follow `outerRadius = innerRadius + padding`
201- [ ] Depth uses semi-transparent shadow; structure uses border
202- [ ] Every `transition` specifies exact properties (no `transition: all`)
203- [ ] Hit areas meet 44×44px (touch) / 40×40px (desktop) minimum, no overlap
204- [ ] Dynamic numbers use `tabular-nums`; headings use `text-wrap: balance`
205- [ ] Icons use one stroke weight matching text; states via `currentColor`, not separate assets
206- [ ] First render skips enter animation (`initial={false}` or equivalent)
207- [ ] High-frequency interactions have no custom animation; motion is not the only feedback
208
209<!-- moai:evolvable-end -->