ui-ux-pro-max-skill/cli/assets/templates/base/skill-content.md

{{TITLE}}

{{DESCRIPTION}} {{QUICK_REFERENCE}}

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	"做一个 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?"、"推荐配色"	Step 2 (design system)
Review existing UI	"Review this page for UX issues"、"检查无障碍"	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:

1. Searches domains in parallel (product, style, color, landing, typography)
2. Applies reasoning rules from ui-reasoning.csv to select best matches
3. Returns complete design system: pattern, style, colors, typography, effects
4. 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:

1. When building a specific page (e.g., "Checkout"), first check design-system/pages/checkout.md
2. If the page file exists, its rules override the Master file
3. 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"
Landing structure	landing	--domain landing "hero social-proof"
React Native perf	react	--domain react "rerender memo list"
Web interface a11y	web	--domain web "aria focus keyboard"
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
react	React/Next.js performance	waterfall, bundle, suspense, memo, rerender, cache
web	Web interface guidelines	aria, focus, keyboard, semantic, virtualize
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

• No emojis used as icons (use SVG instead)
• All icons come from a consistent icon family and style
• Official brand assets are used with correct proportions and clear space
• Pressed-state visuals do not shift layout bounds or cause jitter
• Semantic theme tokens are used consistently (no ad-hoc per-screen hardcoded colors)

Interaction

• All tappable elements provide clear pressed feedback (ripple/opacity/elevation)
• Touch targets meet minimum size (>=44x44pt iOS, >=48x48dp Android)
• Micro-interaction timing stays in the 150-300ms range with native-feeling easing
• Disabled states are visually clear and non-interactive
• Screen reader focus order matches visual order, and interactive labels are descriptive
• Gesture regions avoid nested/conflicting interactions (tap/drag/back-swipe conflicts)

Light/Dark Mode

• Primary text contrast >=4.5:1 in both light and dark mode
• Secondary text contrast >=3:1 in both light and dark mode
• Dividers/borders and interaction states are distinguishable in both modes
• Modal/drawer scrim opacity is strong enough to preserve foreground legibility (typically 40-60% black)
• Both themes are tested before delivery (not inferred from a single theme)

Layout

• Safe areas are respected for headers, tab bars, and bottom CTA bars
• Scroll content is not hidden behind fixed/sticky bars
• Verified on small phone, large phone, and tablet (portrait + landscape)
• Horizontal insets/gutters adapt correctly by device size and orientation
• 4/8dp spacing rhythm is maintained across component, section, and page levels
• Long-form text measure remains readable on larger devices (no edge-to-edge paragraphs)

Accessibility

• All meaningful images/icons have accessibility labels
• Form fields have labels, hints, and clear error messages
• Color is not the only indicator
• Reduced motion and dynamic text size are supported without layout breakage
• Accessibility traits/roles/states (selected, disabled, expanded) are announced correctly