Prerequisites
Check if Python is installed:
python3 --version || python --version
If Python is not installed, install it based on user's OS:
macOS:
brew install python3
Ubuntu/Debian:
sudo apt update && sudo apt install python3
Windows:
winget install Python.Python.3.12
How to Use This Skill
Use this skill when the user requests any of the following:
| Scenario |
Trigger Examples |
Start From |
| New project / page |
"Build a landing page", "Build a dashboard" |
Step 1 → Step 2 (design system) |
| New component |
"Create a pricing card", "Add a modal" |
Step 3 (domain search: style, ux) |
| Choose style / color / font |
"What style fits a fintech app?", "Recommend a color palette" |
Step 2 (design system) |
| Review existing UI |
"Review this page for UX issues", "Check accessibility" |
Quick Reference checklist above |
| Fix a UI bug |
"Button hover is broken", "Layout shifts on load" |
Quick Reference → relevant section |
| Improve / optimize |
"Make this faster", "Improve mobile experience" |
Step 3 (domain search: ux, react) |
| Implement dark mode |
"Add dark mode support" |
Step 3 (domain: style "dark mode") |
| Add charts / data viz |
"Add an analytics dashboard chart" |
Step 3 (domain: chart) |
| Stack best practices |
"React performance tips"、"SwiftUI navigation" |
Step 4 (stack search) |
Follow this workflow:
Step 1: Analyze User Requirements
Extract key information from user request:
- Product type: Entertainment (social, video, music, gaming), Tool (scanner, editor, converter), Productivity (task manager, notes, calendar), or hybrid
- Target audience: C-end consumer users; consider age group, usage context (commute, leisure, work)
- Style keywords: playful, vibrant, minimal, dark mode, content-first, immersive, etc.
- Stack: React Native (this project's only tech stack)
Step 2: Generate Design System (REQUIRED)
Always start with --design-system to get comprehensive recommendations with reasoning:
python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
This command:
- Searches domains in parallel (product, style, color, landing, typography)
- Applies reasoning rules from
ui-reasoning.csv to select best matches
- Returns complete design system: pattern, style, colors, typography, effects
- Includes anti-patterns to avoid
Example:
python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
Step 2b: Persist Design System (Master + Overrides Pattern)
To save the design system for hierarchical retrieval across sessions, add --persist:
python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
This creates:
design-system/MASTER.md — Global Source of Truth with all design rules
design-system/pages/ — Folder for page-specific overrides
With page-specific override:
python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
This also creates:
design-system/pages/dashboard.md — Page-specific deviations from Master
How hierarchical retrieval works:
- When building a specific page (e.g., "Checkout"), first check
design-system/pages/checkout.md
- If the page file exists, its rules override the Master file
- If not, use
design-system/MASTER.md exclusively
Context-aware retrieval prompt:
I am building the [Page Name] page. Please read design-system/MASTER.md.
Also check if design-system/pages/[page-name].md exists.
If the page file exists, prioritize its rules.
If not, use the Master rules exclusively.
Now, generate the code...
Step 3: Supplement with Detailed Searches (as needed)
After getting the design system, use domain searches to get additional details:
python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
When to use detailed searches:
| Need |
Domain |
Example |
| Product type patterns |
product |
--domain product "entertainment social" |
| More style options |
style |
--domain style "glassmorphism dark" |
| Color palettes |
color |
--domain color "entertainment vibrant" |
| Font pairings |
typography |
--domain typography "playful modern" |
| Chart recommendations |
chart |
--domain chart "real-time dashboard" |
| UX best practices |
ux |
--domain ux "animation accessibility" |
| Alternative fonts |
typography |
--domain typography "elegant luxury" |
| Individual Google Fonts |
google-fonts |
--domain google-fonts "sans serif popular variable" |
| Landing structure |
landing |
--domain landing "hero social-proof" |
| React Native perf |
react |
--domain react "rerender memo list" |
| App interface a11y |
web |
--domain web "accessibilityLabel touch safe-areas" |
| AI prompt / CSS keywords |
prompt |
--domain prompt "minimalism" |
Step 4: Stack Guidelines (React Native)
Get React Native implementation-specific best practices:
python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack react-native
Search Reference
Available Domains
| Domain |
Use For |
Example Keywords |
product |
Product type recommendations |
SaaS, e-commerce, portfolio, healthcare, beauty, service |
style |
UI styles, colors, effects |
glassmorphism, minimalism, dark mode, brutalism |
typography |
Font pairings, Google Fonts |
elegant, playful, professional, modern |
color |
Color palettes by product type |
saas, ecommerce, healthcare, beauty, fintech, service |
landing |
Page structure, CTA strategies |
hero, hero-centric, testimonial, pricing, social-proof |
chart |
Chart types, library recommendations |
trend, comparison, timeline, funnel, pie |
ux |
Best practices, anti-patterns |
animation, accessibility, z-index, loading |
google-fonts |
Individual Google Fonts lookup |
sans serif, monospace, japanese, variable font, popular |
react |
React/Next.js performance |
waterfall, bundle, suspense, memo, rerender, cache |
web |
App interface guidelines (iOS/Android/React Native) |
accessibilityLabel, touch targets, safe areas, Dynamic Type |
prompt |
AI prompts, CSS keywords |
(style name) |
Available Stacks
| Stack |
Focus |
react-native |
Components, Navigation, Lists |
Example Workflow
User request: "Make an AI search homepage."
Step 1: Analyze Requirements
- Product type: Tool (AI search engine)
- Target audience: C-end users looking for fast, intelligent search
- Style keywords: modern, minimal, content-first, dark mode
- Stack: React Native
Step 2: Generate Design System (REQUIRED)
python3 skills/ui-ux-pro-max/scripts/search.py "AI search tool modern minimal" --design-system -p "AI Search"
Output: Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
Step 3: Supplement with Detailed Searches (as needed)
# Get style options for a modern tool product
python3 skills/ui-ux-pro-max/scripts/search.py "minimalism dark mode" --domain style
# Get UX best practices for search interaction and loading
python3 skills/ui-ux-pro-max/scripts/search.py "search loading animation" --domain ux
Step 4: Stack Guidelines
python3 skills/ui-ux-pro-max/scripts/search.py "list performance navigation" --stack react-native
Then: Synthesize design system + detailed searches and implement the design.
Output Formats
The --design-system flag supports two output formats:
# ASCII box (default) - best for terminal display
python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
# Markdown - best for documentation
python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
Tips for Better Results
Query Strategy
- Use multi-dimensional keywords — combine product + industry + tone + density:
"entertainment social vibrant content-dense" not just "app"
- Try different keywords for the same need:
"playful neon" → "vibrant dark" → "content-first minimal"
- Use
--design-system first for full recommendations, then --domain to deep-dive any dimension you're unsure about
- Always add
--stack react-native for implementation-specific guidance
Common Sticking Points
| Problem |
What to Do |
| Can't decide on style/color |
Re-run --design-system with different keywords |
| Dark mode contrast issues |
Quick Reference §6: color-dark-mode + color-accessible-pairs |
| Animations feel unnatural |
Quick Reference §7: spring-physics + easing + exit-faster-than-enter |
| Form UX is poor |
Quick Reference §8: inline-validation + error-clarity + focus-management |
| Navigation feels confusing |
Quick Reference §9: nav-hierarchy + bottom-nav-limit + back-behavior |
| Layout breaks on small screens |
Quick Reference §5: mobile-first + breakpoint-consistency |
| Performance / jank |
Quick Reference §3: virtualize-lists + main-thread-budget + debounce-throttle |
Pre-Delivery Checklist
- Run
--domain ux "animation accessibility z-index loading" as a UX validation pass before implementation
- Run through Quick Reference §1–§3 (CRITICAL + HIGH) as a final review
- Test on 375px (small phone) and landscape orientation
- Verify behavior with reduced-motion enabled and Dynamic Type at largest size
- Check dark mode contrast independently (don't assume light mode values work)
- Confirm all touch targets ≥44pt and no content hidden behind safe areas
Common Rules for Professional UI
These are frequently overlooked issues that make UI look unprofessional:
Scope notice: The rules below are for App UI (iOS/Android/React Native/Flutter), not desktop-web interaction patterns.
Icons & Visual Elements
| Rule |
Standard |
Avoid |
Why It Matters |
| No Emoji as Structural Icons |
Use vector-based icons (e.g., Lucide, react-native-vector-icons, @expo/vector-icons). |
Using emojis (🎨 🚀 ⚙️) for navigation, settings, or system controls. |
Emojis are font-dependent, inconsistent across platforms, and cannot be controlled via design tokens. |
| Vector-Only Assets |
Use SVG or platform vector icons that scale cleanly and support theming. |
Raster PNG icons that blur or pixelate. |
Ensures scalability, crisp rendering, and dark/light mode adaptability. |
| Stable Interaction States |
Use color, opacity, or elevation transitions for press states without changing layout bounds. |
Layout-shifting transforms that move surrounding content or trigger visual jitter. |
Prevents unstable interactions and preserves smooth motion/perceived quality on mobile. |
| Correct Brand Logos |
Use official brand assets and follow their usage guidelines (spacing, color, clear space). |
Guessing logo paths, recoloring unofficially, or modifying proportions. |
Prevents brand misuse and ensures legal/platform compliance. |
| Consistent Icon Sizing |
Define icon sizes as design tokens (e.g., icon-sm, icon-md = 24pt, icon-lg). |
Mixing arbitrary values like 20pt / 24pt / 28pt randomly. |
Maintains rhythm and visual hierarchy across the interface. |
| Stroke Consistency |
Use a consistent stroke width within the same visual layer (e.g., 1.5px or 2px). |
Mixing thick and thin stroke styles arbitrarily. |
Inconsistent strokes reduce perceived polish and cohesion. |
| Filled vs Outline Discipline |
Use one icon style per hierarchy level. |
Mixing filled and outline icons at the same hierarchy level. |
Maintains semantic clarity and stylistic coherence. |
| Touch Target Minimum |
Minimum 44×44pt interactive area (use hitSlop if icon is smaller). |
Small icons without expanded tap area. |
Meets accessibility and platform usability standards. |
| Icon Alignment |
Align icons to text baseline and maintain consistent padding. |
Misaligned icons or inconsistent spacing around them. |
Prevents subtle visual imbalance that reduces perceived quality. |
| Icon Contrast |
Follow WCAG contrast standards: 4.5:1 for small elements, 3:1 minimum for larger UI glyphs. |
Low-contrast icons that blend into the background. |
Ensures accessibility in both light and dark modes. |
Interaction (App)
| Rule |
Do |
Don't |
| Tap feedback |
Provide clear pressed feedback (ripple/opacity/elevation) within 80-150ms |
No visual response on tap |
| Animation timing |
Keep micro-interactions around 150-300ms with platform-native easing |
Instant transitions or slow animations (>500ms) |
| Accessibility focus |
Ensure screen reader focus order matches visual order and labels are descriptive |
Unlabeled controls or confusing focus traversal |
| Disabled state clarity |
Use disabled semantics (disabled/native disabled props), reduced emphasis, and no tap action |
Controls that look tappable but do nothing |
| Touch target minimum |
Keep tap areas >=44x44pt (iOS) or >=48x48dp (Android), expand hit area when icon is smaller |
Tiny tap targets or icon-only hit areas without padding |
| Gesture conflict prevention |
Keep one primary gesture per region and avoid nested tap/drag conflicts |
Overlapping gestures causing accidental actions |
| Semantic native controls |
Prefer native interactive primitives (Button, Pressable, platform equivalents) with proper accessibility roles |
Generic containers used as primary controls without semantics |
Light/Dark Mode Contrast
| Rule |
Do |
Don't |
| Surface readability (light) |
Keep cards/surfaces clearly separated from background with sufficient opacity/elevation |
Overly transparent surfaces that blur hierarchy |
| Text contrast (light) |
Maintain body text contrast >=4.5:1 against light surfaces |
Low-contrast gray body text |
| Text contrast (dark) |
Maintain primary text contrast >=4.5:1 and secondary text >=3:1 on dark surfaces |
Dark mode text that blends into background |
| Border and divider visibility |
Ensure separators are visible in both themes (not just light mode) |
Theme-specific borders disappearing in one mode |
| State contrast parity |
Keep pressed/focused/disabled states equally distinguishable in light and dark themes |
Defining interaction states for one theme only |
| Token-driven theming |
Use semantic color tokens mapped per theme across app surfaces/text/icons |
Hardcoded per-screen hex values |
| Scrim and modal legibility |
Use a modal scrim strong enough to isolate foreground content (typically 40-60% black) |
Weak scrim that leaves background visually competing |
Layout & Spacing
| Rule |
Do |
Don't |
| Safe-area compliance |
Respect top/bottom safe areas for all fixed headers, tab bars, and CTA bars |
Placing fixed UI under notch, status bar, or gesture area |
| System bar clearance |
Add spacing for status/navigation bars and gesture home indicator |
Let tappable content collide with OS chrome |
| Consistent content width |
Keep predictable content width per device class (phone/tablet) |
Mixing arbitrary widths between screens |
| 8dp spacing rhythm |
Use a consistent 4/8dp spacing system for padding/gaps/section spacing |
Random spacing increments with no rhythm |
| Readable text measure |
Keep long-form text readable on large devices (avoid edge-to-edge paragraphs on tablets) |
Full-width long text that hurts readability |
| Section spacing hierarchy |
Define clear vertical rhythm tiers (e.g., 16/24/32/48) by hierarchy |
Similar UI levels with inconsistent spacing |
| Adaptive gutters by breakpoint |
Increase horizontal insets on larger widths and in landscape |
Same narrow gutter on all device sizes/orientations |
| Scroll and fixed element coexistence |
Add bottom/top content insets so lists are not hidden behind fixed bars |
Scroll content obscured by sticky headers/footers |
Pre-Delivery Checklist
Before delivering UI code, verify these items:
Scope notice: This checklist is for App UI (iOS/Android/React Native/Flutter).
Visual Quality
Interaction
Light/Dark Mode
Layout
Accessibility
1---2name: ui-ux-pro-max3metadata:4 source: https://skillmd.com/skills/auto-skiller/ui-ux-pro-max5 name: ui-ux-pro-max6 class: toolboxes7 type: skill8 version: '1.0'9 schema_version: '1.0'10 freshness:11 status: active12 sync_count: 013 last_synced_by: daemon14 last_synced: '2026-06-27T00:00:00'15credentials:16 maturity: "functional"17 description: "UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples."18 when_to_use: "Use when applicable"19 triggers: []20 inputs: []21 outputs: []22---232425## Prerequisites2627Check if Python is installed:2829```bash30python3 --version || python --version31```3233If Python is not installed, install it based on user's OS:3435**macOS:**36```bash37brew install python338```3940**Ubuntu/Debian:**41```bash42sudo apt update && sudo apt install python343```4445**Windows:**46```powershell47winget install Python.Python.3.1248```4950---5152## How to Use This Skill5354Use this skill when the user requests any of the following:5556| Scenario | Trigger Examples | Start From |57|----------|-----------------|------------|58| **New project / page** | "Build a landing page", "Build a dashboard" | Step 1 → Step 2 (design system) |59| **New component** | "Create a pricing card", "Add a modal" | Step 3 (domain search: style, ux) |60| **Choose style / color / font** | "What style fits a fintech app?", "Recommend a color palette" | Step 2 (design system) |61| **Review existing UI** | "Review this page for UX issues", "Check accessibility" | Quick Reference checklist above |62| **Fix a UI bug** | "Button hover is broken", "Layout shifts on load" | Quick Reference → relevant section |63| **Improve / optimize** | "Make this faster", "Improve mobile experience" | Step 3 (domain search: ux, react) |64| **Implement dark mode** | "Add dark mode support" | Step 3 (domain: style "dark mode") |65| **Add charts / data viz** | "Add an analytics dashboard chart" | Step 3 (domain: chart) |66| **Stack best practices** | "React performance tips"、"SwiftUI navigation" | Step 4 (stack search) |6768Follow this workflow:6970### Step 1: Analyze User Requirements7172Extract key information from user request:73- **Product type**: Entertainment (social, video, music, gaming), Tool (scanner, editor, converter), Productivity (task manager, notes, calendar), or hybrid74- **Target audience**: C-end consumer users; consider age group, usage context (commute, leisure, work)75- **Style keywords**: playful, vibrant, minimal, dark mode, content-first, immersive, etc.76- **Stack**: React Native (this project's only tech stack)7778### Step 2: Generate Design System (REQUIRED)7980**Always start with `--design-system`** to get comprehensive recommendations with reasoning:8182```bash83python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]84```8586This command:871. Searches domains in parallel (product, style, color, landing, typography)882. Applies reasoning rules from `ui-reasoning.csv` to select best matches893. Returns complete design system: pattern, style, colors, typography, effects904. Includes anti-patterns to avoid9192**Example:**93```bash94python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"95```9697### Step 2b: Persist Design System (Master + Overrides Pattern)9899To save the design system for **hierarchical retrieval across sessions**, add `--persist`:100101```bash102python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"103```104105This creates:106- `design-system/MASTER.md` — Global Source of Truth with all design rules107- `design-system/pages/` — Folder for page-specific overrides108109**With page-specific override:**110```bash111python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"112```113114This also creates:115- `design-system/pages/dashboard.md` — Page-specific deviations from Master116117**How hierarchical retrieval works:**1181. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`1192. If the page file exists, its rules **override** the Master file1203. If not, use `design-system/MASTER.md` exclusively121122**Context-aware retrieval prompt:**123```124I am building the [Page Name] page. Please read design-system/MASTER.md.125Also check if design-system/pages/[page-name].md exists.126If the page file exists, prioritize its rules.127If not, use the Master rules exclusively.128Now, generate the code...129```130131### Step 3: Supplement with Detailed Searches (as needed)132133After getting the design system, use domain searches to get additional details:134135```bash136python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]137```138139**When to use detailed searches:**140141| Need | Domain | Example |142|------|--------|---------|143| Product type patterns | `product` | `--domain product "entertainment social"` |144| More style options | `style` | `--domain style "glassmorphism dark"` |145| Color palettes | `color` | `--domain color "entertainment vibrant"` |146| Font pairings | `typography` | `--domain typography "playful modern"` |147| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |148| UX best practices | `ux` | `--domain ux "animation accessibility"` |149| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |150| Individual Google Fonts | `google-fonts` | `--domain google-fonts "sans serif popular variable"` |151| Landing structure | `landing` | `--domain landing "hero social-proof"` |152| React Native perf | `react` | `--domain react "rerender memo list"` |153| App interface a11y | `web` | `--domain web "accessibilityLabel touch safe-areas"` |154| AI prompt / CSS keywords | `prompt` | `--domain prompt "minimalism"` |155156### Step 4: Stack Guidelines (React Native)157158Get React Native implementation-specific best practices:159160```bash161python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack react-native162```163164---165166## Search Reference167168### Available Domains169170| Domain | Use For | Example Keywords |171|--------|---------|------------------|172| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |173| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |174| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |175| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |176| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |177| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |178| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |179| `google-fonts` | Individual Google Fonts lookup | sans serif, monospace, japanese, variable font, popular |180| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |181| `web` | App interface guidelines (iOS/Android/React Native) | accessibilityLabel, touch targets, safe areas, Dynamic Type |182| `prompt` | AI prompts, CSS keywords | (style name) |183184### Available Stacks185186| Stack | Focus |187|-------|-------|188| `react-native` | Components, Navigation, Lists |189190---191192## Example Workflow193194**User request:** "Make an AI search homepage."195196### Step 1: Analyze Requirements197- Product type: Tool (AI search engine)198- Target audience: C-end users looking for fast, intelligent search199- Style keywords: modern, minimal, content-first, dark mode200- Stack: React Native201202### Step 2: Generate Design System (REQUIRED)203204```bash205python3 skills/ui-ux-pro-max/scripts/search.py "AI search tool modern minimal" --design-system -p "AI Search"206```207208**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.209210### Step 3: Supplement with Detailed Searches (as needed)211212```bash213# Get style options for a modern tool product214python3 skills/ui-ux-pro-max/scripts/search.py "minimalism dark mode" --domain style215216# Get UX best practices for search interaction and loading217python3 skills/ui-ux-pro-max/scripts/search.py "search loading animation" --domain ux218```219220### Step 4: Stack Guidelines221222```bash223python3 skills/ui-ux-pro-max/scripts/search.py "list performance navigation" --stack react-native224```225226**Then:** Synthesize design system + detailed searches and implement the design.227228---229230## Output Formats231232The `--design-system` flag supports two output formats:233234```bash235# ASCII box (default) - best for terminal display236python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system237238# Markdown - best for documentation239python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown240```241242---243244## Tips for Better Results245246### Query Strategy247248- Use **multi-dimensional keywords** — combine product + industry + tone + density: `"entertainment social vibrant content-dense"` not just `"app"`249- Try different keywords for the same need: `"playful neon"` → `"vibrant dark"` → `"content-first minimal"`250- Use `--design-system` first for full recommendations, then `--domain` to deep-dive any dimension you're unsure about251- Always add `--stack react-native` for implementation-specific guidance252253### Common Sticking Points254255| Problem | What to Do |256|---------|------------|257| Can't decide on style/color | Re-run `--design-system` with different keywords |258| Dark mode contrast issues | Quick Reference §6: `color-dark-mode` + `color-accessible-pairs` |259| Animations feel unnatural | Quick Reference §7: `spring-physics` + `easing` + `exit-faster-than-enter` |260| Form UX is poor | Quick Reference §8: `inline-validation` + `error-clarity` + `focus-management` |261| Navigation feels confusing | Quick Reference §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior` |262| Layout breaks on small screens | Quick Reference §5: `mobile-first` + `breakpoint-consistency` |263| Performance / jank | Quick Reference §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle` |264265### Pre-Delivery Checklist266267- Run `--domain ux "animation accessibility z-index loading"` as a UX validation pass before implementation268- Run through Quick Reference **§1–§3** (CRITICAL + HIGH) as a final review269- Test on 375px (small phone) and landscape orientation270- Verify behavior with **reduced-motion** enabled and **Dynamic Type** at largest size271- Check dark mode contrast independently (don't assume light mode values work)272- Confirm all touch targets ≥44pt and no content hidden behind safe areas273274---275276## Common Rules for Professional UI277278These are frequently overlooked issues that make UI look unprofessional:279Scope notice: The rules below are for App UI (iOS/Android/React Native/Flutter), not desktop-web interaction patterns.280281### Icons & Visual Elements282283| Rule | Standard | Avoid | Why It Matters |284|------|----------|--------|----------------|285| **No Emoji as Structural Icons** | Use vector-based icons (e.g., Lucide, react-native-vector-icons, @expo/vector-icons). | Using emojis (🎨 🚀 ⚙️) for navigation, settings, or system controls. | Emojis are font-dependent, inconsistent across platforms, and cannot be controlled via design tokens. |286| **Vector-Only Assets** | Use SVG or platform vector icons that scale cleanly and support theming. | Raster PNG icons that blur or pixelate. | Ensures scalability, crisp rendering, and dark/light mode adaptability. |287| **Stable Interaction States** | Use color, opacity, or elevation transitions for press states without changing layout bounds. | Layout-shifting transforms that move surrounding content or trigger visual jitter. | Prevents unstable interactions and preserves smooth motion/perceived quality on mobile. |288| **Correct Brand Logos** | Use official brand assets and follow their usage guidelines (spacing, color, clear space). | Guessing logo paths, recoloring unofficially, or modifying proportions. | Prevents brand misuse and ensures legal/platform compliance. |289| **Consistent Icon Sizing** | Define icon sizes as design tokens (e.g., icon-sm, icon-md = 24pt, icon-lg). | Mixing arbitrary values like 20pt / 24pt / 28pt randomly. | Maintains rhythm and visual hierarchy across the interface. |290| **Stroke Consistency** | Use a consistent stroke width within the same visual layer (e.g., 1.5px or 2px). | Mixing thick and thin stroke styles arbitrarily. | Inconsistent strokes reduce perceived polish and cohesion. |291| **Filled vs Outline Discipline** | Use one icon style per hierarchy level. | Mixing filled and outline icons at the same hierarchy level. | Maintains semantic clarity and stylistic coherence. |292| **Touch Target Minimum** | Minimum 44×44pt interactive area (use hitSlop if icon is smaller). | Small icons without expanded tap area. | Meets accessibility and platform usability standards. |293| **Icon Alignment** | Align icons to text baseline and maintain consistent padding. | Misaligned icons or inconsistent spacing around them. | Prevents subtle visual imbalance that reduces perceived quality. |294| **Icon Contrast** | Follow WCAG contrast standards: 4.5:1 for small elements, 3:1 minimum for larger UI glyphs. | Low-contrast icons that blend into the background. | Ensures accessibility in both light and dark modes. |295296297### Interaction (App)298299| Rule | Do | Don't |300|------|----|----- |301| **Tap feedback** | Provide clear pressed feedback (ripple/opacity/elevation) within 80-150ms | No visual response on tap |302| **Animation timing** | Keep micro-interactions around 150-300ms with platform-native easing | Instant transitions or slow animations (>500ms) |303| **Accessibility focus** | Ensure screen reader focus order matches visual order and labels are descriptive | Unlabeled controls or confusing focus traversal |304| **Disabled state clarity** | Use disabled semantics (`disabled`/native disabled props), reduced emphasis, and no tap action | Controls that look tappable but do nothing |305| **Touch target minimum** | Keep tap areas >=44x44pt (iOS) or >=48x48dp (Android), expand hit area when icon is smaller | Tiny tap targets or icon-only hit areas without padding |306| **Gesture conflict prevention** | Keep one primary gesture per region and avoid nested tap/drag conflicts | Overlapping gestures causing accidental actions |307| **Semantic native controls** | Prefer native interactive primitives (`Button`, `Pressable`, platform equivalents) with proper accessibility roles | Generic containers used as primary controls without semantics |308309### Light/Dark Mode Contrast310311| Rule | Do | Don't |312|------|----|----- |313| **Surface readability (light)** | Keep cards/surfaces clearly separated from background with sufficient opacity/elevation | Overly transparent surfaces that blur hierarchy |314| **Text contrast (light)** | Maintain body text contrast >=4.5:1 against light surfaces | Low-contrast gray body text |315| **Text contrast (dark)** | Maintain primary text contrast >=4.5:1 and secondary text >=3:1 on dark surfaces | Dark mode text that blends into background |316| **Border and divider visibility** | Ensure separators are visible in both themes (not just light mode) | Theme-specific borders disappearing in one mode |317| **State contrast parity** | Keep pressed/focused/disabled states equally distinguishable in light and dark themes | Defining interaction states for one theme only |318| **Token-driven theming** | Use semantic color tokens mapped per theme across app surfaces/text/icons | Hardcoded per-screen hex values |319| **Scrim and modal legibility** | Use a modal scrim strong enough to isolate foreground content (typically 40-60% black) | Weak scrim that leaves background visually competing |320321### Layout & Spacing322323| Rule | Do | Don't |324|------|----|----- |325| **Safe-area compliance** | Respect top/bottom safe areas for all fixed headers, tab bars, and CTA bars | Placing fixed UI under notch, status bar, or gesture area |326| **System bar clearance** | Add spacing for status/navigation bars and gesture home indicator | Let tappable content collide with OS chrome |327| **Consistent content width** | Keep predictable content width per device class (phone/tablet) | Mixing arbitrary widths between screens |328| **8dp spacing rhythm** | Use a consistent 4/8dp spacing system for padding/gaps/section spacing | Random spacing increments with no rhythm |329| **Readable text measure** | Keep long-form text readable on large devices (avoid edge-to-edge paragraphs on tablets) | Full-width long text that hurts readability |330| **Section spacing hierarchy** | Define clear vertical rhythm tiers (e.g., 16/24/32/48) by hierarchy | Similar UI levels with inconsistent spacing |331| **Adaptive gutters by breakpoint** | Increase horizontal insets on larger widths and in landscape | Same narrow gutter on all device sizes/orientations |332| **Scroll and fixed element coexistence** | Add bottom/top content insets so lists are not hidden behind fixed bars | Scroll content obscured by sticky headers/footers |333334---335336## Pre-Delivery Checklist337338Before delivering UI code, verify these items:339Scope notice: This checklist is for App UI (iOS/Android/React Native/Flutter).340341### Visual Quality342- [ ] No emojis used as icons (use SVG instead)343- [ ] All icons come from a consistent icon family and style344- [ ] Official brand assets are used with correct proportions and clear space345- [ ] Pressed-state visuals do not shift layout bounds or cause jitter346- [ ] Semantic theme tokens are used consistently (no ad-hoc per-screen hardcoded colors)347348### Interaction349- [ ] All tappable elements provide clear pressed feedback (ripple/opacity/elevation)350- [ ] Touch targets meet minimum size (>=44x44pt iOS, >=48x48dp Android)351- [ ] Micro-interaction timing stays in the 150-300ms range with native-feeling easing352- [ ] Disabled states are visually clear and non-interactive353- [ ] Screen reader focus order matches visual order, and interactive labels are descriptive354- [ ] Gesture regions avoid nested/conflicting interactions (tap/drag/back-swipe conflicts)355356### Light/Dark Mode357- [ ] Primary text contrast >=4.5:1 in both light and dark mode358- [ ] Secondary text contrast >=3:1 in both light and dark mode359- [ ] Dividers/borders and interaction states are distinguishable in both modes360- [ ] Modal/drawer scrim opacity is strong enough to preserve foreground legibility (typically 40-60% black)361- [ ] Both themes are tested before delivery (not inferred from a single theme)362363### Layout364- [ ] Safe areas are respected for headers, tab bars, and bottom CTA bars365- [ ] Scroll content is not hidden behind fixed/sticky bars366- [ ] Verified on small phone, large phone, and tablet (portrait + landscape)367- [ ] Horizontal insets/gutters adapt correctly by device size and orientation368- [ ] 4/8dp spacing rhythm is maintained across component, section, and page levels369- [ ] Long-form text measure remains readable on larger devices (no edge-to-edge paragraphs)370371### Accessibility372- [ ] All meaningful images/icons have accessibility labels373- [ ] Form fields have labels, hints, and clear error messages374- [ ] Color is not the only indicator375- [ ] Reduced motion and dynamic text size are supported without layout breakage376- [ ] Accessibility traits/roles/states (selected, disabled, expanded) are announced correctly377