Horace-Maxwell/ui-master

UI Master: Make Interfaces That Don't Look Like AI Generated

Path Convention: This file is in the ui/ directory of the repository, with catalog/ and prompts/ at the same level, bundled with the skill.

• In the full repository (or when installed via setup.sh --link-skills soft link): first use realpath to find the repository root, then use python3 <repo-root>/scripts/find.py <keyword> to search across all modules.
• Standalone installation (npx skills add Horace-Maxwell/ai-master-prompt, only the ui/ folder): no search script, directly grep catalog/*.md; other modules like scaffolding, Skills, tools see https://github.com/Horace-Maxwell/ai-master-prompt.

AI-generated UIs often look bad—not due to lack of capability, but because: ① existing component libraries aren't used effectively, and ② you can't name the desired effect. This skill solves both.

Workflow

1. First Clarify Four Things

• Platform & Tech Stack: Web (React/Next? Vue? Pure HTML?) or React Native/Expo? Existing project or new?
• Page Type: Landing page / Dashboard / SaaS app / AI chat product / Mobile app / Portfolio…
• Style: Did the user specify a style or reference site?
• Motion Intensity: Minimal / Moderate / Dazzling

When to ask vs. when to act directly: Only ask if platform and page type are unclear (max one round of questions). Use defaults for the rest and state your choices in the response:

Not Said	Default
Tech Stack	Follow existing project; new Web: Next.js + Tailwind + shadcn/ui
Style	Give 2–3 options for the user to choose from (see prompts/style-recipes.md); if user says "you decide," pick the most suitable one for the page type
Motion Intensity	Minimal for product interfaces; Moderate for landing pages; Dazzling for portfolios/event pages

When the user can't describe the effect, use the terms from prompts/effect-vocabulary.md to confirm (e.g., "Do you mean Text Scramble, where letters jump randomly before settling into the correct word?")

2. Choose Foundation Using Decision Table

When the user specifies a style, the style row takes priority: a hand-drawn landing page uses a hand-drawn library; don't stack dark, flashy components like Aceternity on top.

Scenario	Foundation	Add-ons
React/Next new project (default)	npx create-next-app@latest, then npx shadcn@latest init	Add components from namespace registries as needed
Stylized (hand-drawn/retro/brutalist/glass/terminal)	Corresponding style library (see style-recipes)	Most are shadcn registries; install and directly replace same-named components
Landing page / Hero / Marketing page (no specified style)	shadcn + Magic UI / Aceternity / React Bits	Smooth scroll with Lenis; scroll animations with GSAP ScrollTrigger or Motion
Dashboard / Admin panel	shadcn + Tremor or shadcn charts	Kibo UI for advanced components
AI Chat / Agent product	shadcn + AI Elements or assistant-ui	affectUI for agent observability panels; data from Langfuse / Phoenix; Python backend uses AG-UI protocol to connect frontend
React Native / Expo	npx create-expo-app@latest + React Native Reusables or ExpoKit	Liquid glass with expo-glass-effect, frosted glass with expo-blur; beUI for animations
Vue / Nuxt	Nuxt UI or shadcn-vue	Inspira UI for effects; goopUI (liquid effects, pre-alpha)
Pure HTML / No framework	daisyUI or Tailwind + vanilla CSS	Animate.css, Hover.css, GSAP

Full candidate lists:

• Component libraries: catalog/02 Basics, 03 Animations, 04 Stylized, 05 Mobile, 06 Effects/3D, 07 AI Products
• If not found, check aggregator sites: catalog/01 (21st.dev, official shadcn catalog, registry.directory)

3. Install Components: shadcn Namespace Usage

Namespaces listed in the official index (548+) require no prior configuration:

npx shadcn@latest add @magicui/marquee
npx shadcn@latest add @aceternity/spotlight
npx shadcn@latest search @aceternity --query "card"     # If you don't know the entry name: search first
npx shadcn@latest list @magicui                    # Or list all entries in a namespace
npx shadcn@latest view @magicui/border-beam        # See code before installing

Three easy pitfalls to avoid:

1. Don't guess entry names. The <item> in catalogs is a placeholder; each library uses its own naming. Always search or list first.
2. React Bits entry names include variant suffixes: <ComponentName>-<TS|JS>-<TW|CSS>, e.g., npx shadcn@latest add @react-bits/DecryptedText-TS-TW. Omitting the suffix will result in a 404.
3. Libraries not in the official index (Looseleaf, Rare UI, etc.) can be installed in two ways:

   • Directly pass the full URL or GitHub path, zero config: npx shadcn@latest add https://kevintngo.github.io/looseleaf/r/button.json, npx shadcn@latest add swamimalode07/rare-ui/fluid-orb

   • Or register once in components.json, then use @looseleaf/button:

     { "registries": { "@looseleaf": "https://kevintngo.github.io/looseleaf/r/{name}.json" } }
     

Common namespace quick reference (all in the official index): @magicui @aceternity @react-bits @animate-ui @motion-primitives @cult-ui @kokonutui @coss @shadcnblocks @tailark @kibo-ui @8bitcn @neobrutalism @retroui @glasscn @glassyui @ai-elements @assistant-ui @prompt-kit @affectui @beui @shaderscn @threecn @lucide-animated @svgl

4. Set Up Tools for the Agent (with User Consent)

Minimal combination (shown for Claude Code; for other agents, write the same npx… after -- into their MCP config—see the reference table in the repo root AGENTS.md):

npx shadcn@latest mcp init --client claude                    # Browse/install components from hundreds of registries (also supports --client cursor / vscode)
claude mcp add context7 -- npx -y @upstash/context7-mcp        # Latest docs for any library
npx skills add anthropics/skills --skill frontend-design       # Baseline aesthetic, remove AI-taint

Add on demand: Magic UI MCP, 21st MCP, Figma MCP (when you have a design file), Motion AI Kit (npx motion-ai), GSAP skills, reference screenshot tools like Mobbin / Refero / Lazyweb MCP (all require accounts). Full list in catalog/12.

5. Define the Design System First, Then Write Pages

1. Set design tokens: Color palette (generate with Realtime Colors / tweakcn), fonts (don't default to Inter—choose a pair with personality from Fontshare or Google Fonts), border radius, shadow, spacing. If the user provided a reference brand, search for the corresponding DESIGN.md in awesome-design-md and put it in the project root.
2. Page structure: Reference the block order of similar pages from inspiration sites in catalog/10.
3. Prioritize component reuse: Don't hand-write what you can npx shadcn@latest add.
4. Motion with purpose: Entrance once, hover feedback, scroll-driven narrative. Respect prefers-reduced-motion.

6. Self-Check (Don't Skip)

• Open the page screenshot using a browser (Playwright / Chrome DevTools MCP / built-in browser) and check against the "AI-taint" list below
• Check mobile width (375px)
• No console errors; smooth animations (animate only transform/opacity)

Common AI telltale signs (avoid): Purple-blue gradient + Inter font + centered hero title combo; all cards with the same border radius and shadow; emoji as icons; full-page glassmorphism; gray text with no hierarchy; every section "fade in and move up."

When You Need Animation/Style Vocabulary

• Quick reference: prompts/effect-vocabulary.md (includes directly installable entry names)
• Style recipes: prompts/style-recipes.md
• Request template (for users or other AI agents): prompts/request-template.md
• Galleries with demos: motion-prompt (192 effects, npx skills add showheyohtaki/motion-prompt), Motion Library (510 effects), aimotions (195 text animations), see catalog/09