cli/assets/templates/base/skill-content.md
{{DESCRIPTION}} {{QUICK_REFERENCE}}
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
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:
Extract key information from user request:
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:
ui-reasoning.csv to select best matchesExample:
python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
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 rulesdesign-system/pages/ — Folder for page-specific overridesWith 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 MasterHow hierarchical retrieval works:
design-system/pages/checkout.mddesign-system/MASTER.md exclusivelyContext-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...
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" |
| App interface a11y | web | --domain web "accessibilityLabel touch safe-areas" |
| AI prompt / CSS keywords | prompt | --domain prompt "minimalism" |
Get React Native implementation-specific best practices:
python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack react-native
| 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 | App interface guidelines (iOS/Android/React Native) | accessibilityLabel, touch targets, safe areas, Dynamic Type |
prompt | AI prompts, CSS keywords | (style name) |
| Stack | Focus |
|---|---|
react-native | Components, Navigation, Lists |
User request: "Make an AI search homepage。"
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.
# 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
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.
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
"entertainment social vibrant content-dense" not just "app""playful neon" → "vibrant dark" → "content-first minimal"--design-system first for full recommendations, then --domain to deep-dive any dimension you're unsure about--stack react-native for implementation-specific guidance| 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 |
--domain ux "animation accessibility z-index loading" as a UX validation pass before implementationThese 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.
| 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. |
| 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 |
| 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 |
| 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 |
Before delivering UI code, verify these items: Scope notice: This checklist is for App UI (iOS/Android/React Native/Flutter).