UI Audit — Interface and Interaction Review
Design Standards: Minimalism + Animation Storytelling + Minimal Text.
Core Principle: Use visuals instead of text whenever possible, use animation instead of prompts when possible, and when text is necessary, use the fewest words.
Companion Scripts
scripts/scan-ui.sh [DIRECTORY]: Read-only automated scan for text symbols, fuzzy button text, hardcoded Chinese, static loading indicators, undefined CSS classes, and other common UI issues.
Step 0: UI Baseline Check (must be performed before any review)
Navigation Baseline
□ Users can return to the home/main page from any page
□ Users can return to the list page from a detail page
□ Users can enter the create/new flow from a list page
□ Page refresh does not lose the current position
State Handling Baseline
□ Every data load has a loading state (skeleton/spinner)
□ Every API call has an error state (user-visible error message)
□ Every list has an empty state (friendly prompt + action guidance when no data)
□ Form submissions have a disabled state (prevent duplicate submission)
Authentication Baseline
□ Login page has a "Register" entry point
□ Register page has a "Login" entry point
□ After login, navigate to a meaningful page (not a blank screen)
□ After logout, clear state
□ When token expires, automatically redirect to login page
If the baseline fails, fix the baseline first; do not perform any other UI review.
Design Philosophy
Minimalism
□ Each page has only one visual focal point
□ White space is part of the design
□ Use no more than 2 main colors + 1 accent color
□ Use no more than 1 font type
□ No shadows, gradients, or border-radius exceeding 4px
□ Spacing uses multiples of 8px/16px/24px/32px
Animation Storytelling
□ Every state change has a transition animation (150-300ms)
□ List item entries have a stagger animation (30-50ms interval)
□ Button clicks have press feedback (scale: 0.98)
□ Loading uses Skeleton, not a static placeholder
□ Errors use shake animation or color change, not a pop-up
□ Success uses a brief highlight animation, not a toast
Minimal Text
□ Button text does not exceed 4 characters
□ Icon buttons have no text (use tooltip instead)
□ No vague words like "Confirm" or "Cancel" (use "Save" or "Discard" instead)
□ Error messages do not exceed 10 characters
□ Navigation items do not exceed 2 characters + icon
No Text Symbols Allowed
□ No → ← ↑ ↓ (use arrow icon)
□ No × (use close icon)
□ No + - (use add/minus icon)
□ No > < (use Chevron icon)
□ No ✓ ! (use Check/Alert icon)
□ No ~ (use visual separator)
□ No % (use progress bar or ring)
Review Checklist
1. Text Symbol Check (Highest Priority)
Run scripts/scan-ui.sh for automated scanning, then manually confirm each match to replace it with an icon if necessary.
2. Icon System Check
□ Common operation icons are complete: save / trash / edit / arrow-left / x (close)
□ Navigation icons are complete: search / plus / download / upload / external-link
□ All icons are in a consistent style (outline or solid, pick one)
□ Icon sizes are unified (16px for operations, 24px for navigation, 32px for empty states)
□ Icons come from the same icon library (e.g., Lucide / Heroicons / Phosphor), no mixing
3. Animation Check
□ Page transitions have transition animations (fade/slide)
□ List item entries have stagger animations
□ Button clicks have press feedback
□ Loading uses Skeleton animations
□ Modals/dropdowns have expand animations
□ Long-running operations have progress animations
Prohibited: spinning spinners exceeding 2 seconds, flashing labels, infinite loop animations, complex animations that impact performance.
4. i18n Completeness
□ All user-visible text uses the t() function
□ No hardcoded Chinese strings (except in translations files)
□ Error messages use i18n keys
□ aria-label uses i18n
5. CSS Consistency
□ All CSS classes referenced in JSX are defined
□ No unused CSS classes
□ z-index layers are consistent (modal: 200, drawer: 100, backdrop: 99, toast: 300)
□ Colors use CSS variables or theme colors, no hardcoded hex
□ No !important (unless with a clear reason)
6. Dead Code Check
□ All component files are imported by at least one other file
□ No duplicate file names (repeated components in different directories)
□ No unused imports
7. State Handling
□ Every data load has a loading state
□ Every API call has an error state
□ Every list has an empty state
□ Form submissions have a disabled state
□ Long-running operations have cancel/abort support
8. Navigation Flow
□ All routes have corresponding page components
□ Protected routes have auth guards
□ 404 has a friendly fallback page
□ Breadcrumbs/back buttons navigate correctly
□ External links open in a new tab
9. Responsive & Accessibility
□ Mobile layout does not overflow
□ All interactive elements have aria-label
□ Keyboard operable (Tab navigation, Escape to close, Enter to confirm)
□ Modals/panels have focus trap
□ Color contrast meets WCAG AA
Workflow
Phase 1: Automated Scan
Run scripts/scan-ui.sh, collect results. Key focus: text symbols, overly long button text, missing animations, hardcoded Chinese, undefined CSS classes.
Phase 2: Manual Verification
Verify page by page against the design philosophy and review checklist. Use Playwright to take screenshots of each page for comparison.
Phase 3: Fix
Fix in priority order:
- Replace text symbols with icons
- Simplify text
- Add missing animations
- Complete CSS classes
- Complete i18n
- Delete dead code
- State handling
- Navigation flow
Phase 4: Regression Verification
After fixes, re-run the automated scan to confirm no new issues.
Relationship with polish-loop-v2
- polish-loop-v2: General code review (logic, security, performance, runtime)
- ui-audit: Focused on front-end UI and user experience
Run in parallel, with shared baseline checks. Issues from ui-audit have higher priority than those from polish-loop-v2.