ui-ux-pro-max-skill User Guide

UI/UX Pro Max is an AI design-intelligence skill pack for AI coding assistants. Once installed, the skill loads into your assistant (Claude Code, Cursor, Windsurf, Copilot, and 15 other platforms) and gives it access to a structured database of UI styles, color palettes, font pairings, UX guidelines, chart patterns, and per-stack implementation rules. The assistant draws on those references whenever you ask it to design a screen, generate a design system, audit a UI, or pick colors and typography.

The package itself is split into two parts:

• uipro-cli — a small Node.js CLI (binary uipro) whose only job is to copy the skill's instructions, reference data, and search scripts into the right folder for your AI assistant.
• The skill payload — a SKILL.md instruction file plus 33 CSV reference tables, 3 Python fuzzy-search scripts, and a quick-reference markdown shipped under cli/assets/ (npm package) and mirrored under src/ui-ux-pro-max/ (source-of-truth tree).

This guide is for the person installing and using the skill. Everything in it is verified against cli/src/index.ts (the CLI surface), skill.json (the package manifest), and the 18 platform-config JSONs that drive the install.

Important

"Multi-platform" in this project means multiple AI assistants, not multiple operating systems. The CLI runs on macOS, Linux, and Windows, but the platforms it installs the skill for are AI tools (Claude Code, Cursor, Windsurf, Copilot, Kiro, RooCode, Codex, Qoder, Gemini CLI, Trae, OpenCode, Continue, CodeBuddy, Droid/Factory, KiloCode, Warp, Augment, Antigravity).

1. Quick Start

The lowest-friction path: run npx uipro-cli init in any project directory. The CLI auto-detects your AI tool from marker folders (.claude/, .cursor/, .windsurf/, etc.), generates the skill files locally, and exits. Then restart your AI assistant and ask it to design something.

One-line install

npx uipro-cli init

Expected output (auto-detected Claude Code):

UI/UX Pro Max Installer

info Detected: claude
info Installing for: Claude Code (.claude/skills/)
✔ Generated from templates!

info Installed folders:
  + .claude

success UI/UX Pro Max installed successfully!

Next steps:
  1. Restart your AI coding assistant
  2. Try: "Build a landing page for a SaaS product"

Pick the AI tool explicitly

If you want to skip detection, name the platform with -a / --ai:

npx uipro-cli init --ai claude
npx uipro-cli init --ai cursor
npx uipro-cli init --ai windsurf
npx uipro-cli init --ai copilot

The full set of valid values: claude, cursor, windsurf, antigravity, copilot, kiro, roocode, codex, qoder, gemini, trae, opencode, continue, codebuddy, droid, kilocode, warp, augment, all.

Tip

Use --ai all to install the skill for every supported assistant in one shot. This is useful on a workstation where you switch tools regularly — npx uipro-cli init --ai all writes one skill copy per .<tool>/skills/ui-ux-pro-max/ folder.

First prompt after install

Once the install finishes, restart your AI assistant so it picks up the new skill, then send a design request. The skill activates automatically when your prompt mentions UI, UX, design, layout, colors, typography, or a recognized stack.

Build a landing page for a beauty spa with a calm, premium feel.

The assistant runs the skill's search.py and design_system.py scripts against the bundled CSVs to choose a UI style, color palette, font pairing, and matching component patterns, then produces code in your project's stack.

Note

The CLI never makes design decisions itself — those happen inside your AI assistant after restart. The CLI just writes files. If your assistant ignores design requests after a fresh install, the most common cause is a missed restart.

2. Installation

The default install method is the uipro-cli init template generator. It needs no GitHub access, no admin rights, and writes only to either your current project (cwd) or your home directory (with --global). The optional --legacy ZIP-download path exists for historical pinning but is not the recommended path for new users.

System requirements

Run the install

The simplest path is npx, which downloads and runs the latest published version of the CLI on demand without leaving anything in your global npm tree.

# In your project directory
npx uipro-cli init

If you prefer a permanent install:

# Install once, then call directly
npm install -g uipro-cli
uipro init

Or with bun (the project itself is built with bun):

bunx uipro-cli init

Important

npx aggressively caches the binary it downloads. After upgrading the package, npx uipro-cli init may keep running an old version. If you hit error: unknown option '--global' (issue #215), clear the cache with npx clear-npx-cache or pin to the latest with npx uipro-cli@latest init.

What gets written

The CLI writes a single skill folder under your project (or home directory with --global). For Claude Code:

.claude/
  skills/
    ui-ux-pro-max/
      SKILL.md            # the instruction file the AI loads
      data/               # 33 CSV reference tables
      scripts/            # 3 Python search scripts

For Cursor it writes .cursor/skills/ui-ux-pro-max/ and .shared/. The exact folder name per platform is in section 4.

Post-install verification

ls -la .claude/skills/ui-ux-pro-max/

Expected output:

drwxr-xr-x  5 user group   160B  date .
drwxr-xr-x  3 user group    96B  date ..
-rw-r--r--  1 user group   ...   SKILL.md
drwxr-xr-x  ...               data
drwxr-xr-x  ...               scripts

Restart your AI assistant — VS Code reload, or quit-and-reopen for desktop apps — so the new skill is registered.

Warning

Do not edit SKILL.md, files under data/, or files under scripts/ in place. Re-running uipro init (or uipro update) will overwrite them and you will lose changes. To customize the skill, fork the repo and install from your fork.

Install troubleshooting (10 common entries)

Tip

Most reported install failures come from the --legacy path hitting GitHub rate limits. The default template path does not touch GitHub during init, so when in doubt drop --legacy.

3. Configuration

The skill itself has no user-editable configuration file. There is no .uiproconfig, no uipro.json, no environment variable that changes its behavior. All configuration lives in two places:

• CLI flags at install time — --ai, --force, --offline, --global, --legacy. These pick which platform and where to write, not how the skill behaves at runtime.
• Per-platform JSON configs shipped with the package — cli/assets/templates/platforms/<platform>.json. These are read by cli/src/utils/template.ts to render the right SKILL.md flavor for each AI tool. They are not user-editable; they ship with the package and update on every reinstall.

CLI flags

Run npx uipro-cli --help to see the full list, and npx uipro-cli <command> --help for per-command flags.

Project install vs global install

The default behavior is project-scoped: the skill is written under the current working directory, lives alongside your code, and applies only when you open that project in your AI assistant.

cd my-project
npx uipro-cli init             # writes ./.claude/skills/ui-ux-pro-max/...

Pass --global to install once for your user account so every project sees the skill:

npx uipro-cli init --global    # writes ~/.claude/skills/ui-ux-pro-max/...

Note

Some AI assistants (notably Claude Code) merge global and project skills, so a global install plus an in-project install is harmless duplication. Others may pick one or the other. Issue #185 (closed, by way of issue #75) drove the addition of the --global flag specifically because earlier versions only offered a global write path that "polluted" project context.

Switching project after a global install

A global install does not lock you in. Re-run npx uipro-cli init inside any specific project to add a project-scoped copy that takes precedence (the assistant's own resolution rules decide which one wins).

Warning

The --global flag is not supported in --legacy mode. The CLI will print --global is not supported with --legacy mode, installing locally instead and fall back to a local install. If you need a global install, use the default template path (drop --legacy).

4. Core Usage

The skill activates inside your AI assistant when it sees design-related intent in your prompt. There is nothing to import, no command to run by hand, and no custom syntax — you write a normal request and the assistant handles loading the skill automatically.

How activation works

1. You install the skill with uipro init. The CLI writes SKILL.md plus reference data into the assistant's skills folder.
2. You restart the assistant so it indexes the new skill.
3. You send a prompt that contains design intent. Examples that activate the skill:
   • "Build a landing page for a SaaS product."
   • "Generate a design system for a fintech app, calming and trustworthy."
   • "Audit this dashboard for UX issues."
   • "Pick a font pairing for a children's book platform."
   • "What color palette would suit a coffee brand?"
4. The assistant loads SKILL.md, follows its instructions, and runs the bundled Python scripts against the CSV data to make design decisions.

Important

The skill is read at AI inference time, not at install time. If you change SKILL.md (don't — see section 2) or your assistant fails to reload after an install, the new instructions never reach the model. Always restart after a fresh init or update.

What kinds of design questions the skill answers

The skill is purpose-built for these intents:

• Design a new UI from a brief. "Landing page for a beauty spa." The skill picks a UI style from styles.csv, a palette from colors.csv, a typography pairing from google-fonts.csv and typography.csv, and stitches them into a screen using the matching layout in landing.csv and the per-stack implementation rules.
• Generate a complete design system. Given a project description, the skill produces a coherent system: primary/secondary/accent colors, headline + body fonts, spacing scale, component shapes, do/don't lists. The design_system.py script ties the CSV tables together.
• Audit an existing UI. Paste a screenshot or component code; the skill compares against ux-guidelines.csv (99 guidelines), ui-reasoning.csv (style rationale), and stack-specific rules.
• Pick colors or typography. "Give me 5 palette options for a calm fintech brand" — the skill filters colors.csv (161 palettes) and google-fonts.csv (57 pairings) by mood/industry tags.
• Choose chart patterns. "What chart should I use for time-series with 3 categories?" — charts.csv documents 25 chart types with use-cases.
• Suggest implementation patterns for a stack. Stack CSVs under data/stacks/ contain implementation rules for 16 frameworks (see Reference categories below).

Reference categories shipped in the skill

The skill payload is a structured catalog of design intelligence. Every category is a CSV the assistant reads or fuzzy-searches. Filenames are taken from the file tree.

Stack-specific rule files

The skill ships per-stack rule tables under data/stacks/. These tell the AI how to translate a chosen design system into idiomatic code for the user's framework.

Bundled Python search scripts

The skill ships three Python files that the AI invokes through its tool-call surface — they are not meant to be run by humans directly.

Per-platform install footprint

Each AI tool has a folder convention encoded in cli/src/types/index.ts (AI_FOLDERS) and a SKILL.md flavor in cli/assets/templates/platforms/<tool>.json.

Note

The .shared/ folder is included for backward compatibility with platforms whose ZIP-based install layouts predated the unified template path. Newer platforms (kilocode, warp, augment) include .shared/ as a no-op so uninstall behaves the same way for everyone.

5. Common Tasks

Five concrete recipes covering the tasks users hit most often.

Recipe 1 — Design a new component or screen with the skill loaded

Goal: ask the AI for a fresh design and have it use the skill's reference data.

Steps:

1. Install the skill into your project (npx uipro-cli init).

2. Restart your AI assistant.

3. Open the project in the assistant and prompt with design intent. Examples:

   Design a pricing page for a developer-tools SaaS. Stack: Next.js + Tailwind + shadcn/ui.
   

   Build a settings screen for a mobile-first React Native app, calm and trustworthy.
   

4. The assistant will load the skill, run search.py against colors.csv, styles.csv, typography.csv, the matching pattern CSV (here: landing.csv), and the stack CSV (here: stacks/react.csv or stacks/shadcn.csv), then produce a design plan and the code.

5. Iterate by feeding constraints: "use a single-color palette", "go bolder", "match this brand color".

Recipe 2 — Audit an existing UI

Goal: get critique on a UI you already have.

Steps:

1. Paste a screenshot or the component's source code into your assistant.

2. Ask explicitly:

   Audit this UI against your UX guidelines. List the top 5 issues by impact, and explain each with a fix.
   

3. The skill compares the input against ux-guidelines.csv (99 entries) and ui-reasoning.csv, then returns a prioritized list with rationale.

4. Optionally ask for a redesigned version: "Now produce the same screen with those issues fixed."

Tip

The audit output is more useful when you tell the assistant the target audience ("first-time visitor", "returning power user", "B2B buyer") because the UX guidelines weight differently per audience.

Recipe 3 — Generate a complete design system from a brief

Goal: produce a coherent style + palette + typography + spacing + component-shape spec.

Steps:

1. Frame the brief precisely. Include industry, audience, mood, and stack:

   Generate a design system for a children's reading app. Audience: kids 5–10 and their parents.
   Mood: playful but trustworthy. Stack: React Native.
   

2. The skill calls design_system.py, which combines:

   • One UI style from styles.csv
   • One color palette from colors.csv
   • One typography pairing from google-fonts.csv and typography.csv
   • The matching layout patterns from app-interface.csv
   • Stack-specific implementation rules from stacks/react-native.csv

3. Save the response. Hand the design system to engineering as the basis for component implementation.

Recipe 4 — Get critique on a wireframe

Goal: validate a low-fidelity sketch before investing in high-fidelity design.

Steps:

1. Describe (or share an image of) the wireframe.

2. Ask:

   Critique this wireframe for a checkout flow. Is the information hierarchy correct?
   What's missing for a first-time buyer? What patterns from your data would you swap in?
   

3. The skill cross-references against draft.csv (early-stage rules) and ux-guidelines.csv.

4. The assistant returns concrete swaps ("move the trust badges above the price", "merge step 2 and 3", "the empty cart state is missing").

Recipe 5 — Choose colors or typography in isolation

Goal: pick a palette or font pairing without committing to a full redesign.

Steps:

Give me 5 color palettes for a calm wellness brand. Show hex codes and explain the mood of each.

Suggest 3 Google Fonts pairings for a finance dashboard — clean, readable on small screens.

The skill filters colors.csv and google-fonts.csv by mood/industry tags and returns ranked options with rationale.

Tip

When the assistant offers options, ask "show me how palette #2 would render on the hero section" — that triggers a render of the choice in your stack and surfaces problems before you commit.

Recipe 6 — Pick the right chart for a data shape

Goal: avoid bad chart choices.

Steps:

I have 5 product categories tracked monthly over the last 12 months. What chart should I use,
and what should I avoid?

The skill consults charts.csv (25 chart types), explains the trade-offs, and warns against common misuses (pie chart with 12 slices, dual-Y-axis, truncated baselines).

6. Troubleshooting

Format used throughout: Error / Cause / Solution / Prevention. The errors below are the literal strings the CLI emits, taken from the source.

Error: error: unknown option '--global'

Cause: Stale npx-cached binary still on a pre-2.5.0 version that didn't have --global. Tracked as issue #215.

Solution:

1. Clear the npx cache: npx clear-npx-cache.
2. Re-run pinning to latest: npx uipro-cli@latest init --global.
3. Or uninstall any global copy first: npm uninstall -g uipro-cli, then npx uipro-cli@latest init --global.

Prevention: Always use @latest when running through npx after a known release.

Error: env: node: No such file or directory

Cause: Node is not on PATH, or you installed Node via a non-default mechanism (asdf/nvm/volta) and the shell session can't find it. Tracked as issue #50.

Solution:

1. Verify with which node (macOS/Linux) or where node (Windows).
2. If empty, add Node to PATH or reinstall from https://nodejs.org/.
3. Open a new terminal so the updated PATH takes effect.

Prevention: Pick one Node version manager and use it consistently.

Error: GitHub API rate limit exceeded. Resets at <time>

Cause: You ran in --legacy mode and exceeded the anonymous-rate ceiling on GitHub's REST API. The CLI checks x-ratelimit-remaining on every response.

Solution:

1. Drop --legacy — the default template path does not call GitHub during init.
2. Or wait until the printed reset time.
3. Or set a GITHUB_TOKEN environment variable in your shell to raise the per-hour limit.

Prevention: Use the default install path. --legacy is only needed for very specific pinning scenarios.

Error: GitHub API rate limit exceeded (429 Too Many Requests)

Cause: Same root cause as above — the HTTP 429 path of the same rate-limit guard.

Solution: Same as above.

Prevention: Same as above.

Error: Failed to fetch latest release: 403 Forbidden

Cause: GitHub returned 403 — usually rate-limited but possibly a token issue or repo visibility change.

Solution:

1. Drop --legacy to skip GitHub entirely.
2. If you must use --legacy, supply a valid GITHUB_TOKEN.

Prevention: Default path.

Error: Failed to fetch releases: <status>

Cause: Transient network/CDN fault during uipro versions or uipro update.

Solution: Re-run after a moment. init is unaffected (it doesn't call this code path on the template default).

Prevention: None needed — transient.

Error: Failed to download: <status>

Cause: Asset URL 404'd — the release lacks a ZIP asset and the auto-archive URL also failed.

Solution: Drop --legacy and use the template path.

Prevention: Default path.

Error: No ZIP asset found in latest release

Cause: The latest release is template-only; no uploaded ZIP asset exists for --legacy to download. The CLI auto-falls back to the GitHub auto-archive URL — if that also fails, you see this message.

Solution: Drop --legacy. The template path (default) does not need any release asset.

Prevention: Default path.

Error: Invalid AI type: <foo> / Unknown AI type: <foo>

Cause: Either the CLI top-level allow-list (Invalid) or the template loader's mapping (Unknown) didn't recognize the value passed to --ai.

Solution: Pick from the supported list (section 1 has the full set), or run uipro init with no --ai flag and choose from the interactive prompt.

Prevention: Run with no --ai flag — auto-detection plus the interactive picker is the safer path.

Error: Failed to extract zip: <error>

Cause: PowerShell missing on Windows, or unzip missing on macOS/Linux. Only relevant in --legacy mode.

Solution: Install unzip (apt install unzip, brew install unzip) or run on a Windows host with PowerShell. Or drop --legacy.

Prevention: Default template path bypasses ZIP entirely.

Error: AI assistant doesn't seem to use the skill

Cause: Most often a missed restart, a missed prompt-trigger word, or an install in the wrong folder.

Solution:

1. Restart the assistant after install.
2. Verify the install: ls -la .<tool>/skills/ui-ux-pro-max/ should show SKILL.md, data/, scripts/.
3. Use design-intent words in your prompt ("design", "UI", "UX", "layout", "color", "typography").
4. If you used --global, confirm your assistant picks up ~/.<tool>/skills/ (some don't — re-install per project).
5. See issue #181 for the broader "how should Claude Code use this skill?" discussion.

Prevention: Always restart after install or update.

Error: Generated designs feel chaotic / off-brand

Cause: The skill chooses styles based on the brief — a vague brief gets a generic answer. Tracked as issue #263.

Solution: Be explicit about industry, audience, mood, and stack in the prompt. "Build a landing page" is too vague; "Build a landing page for a calm B2B fintech, Next.js + Tailwind, premium feel" is specific enough to drive a confident choice.

Prevention: Use the recipe templates in section 5.

Error: Sub-skill name frontmatter doesn't match directory name

Cause: The skill's YAML frontmatter name: field disagrees with the directory it lives in. Tracked as issue #266.

Solution: Re-run npx uipro-cli@latest init --force to overwrite with the current package.

Prevention: Avoid editing SKILL.md in place.

Error: Windsurf SKILL.md generated without YAML frontmatter

Cause: Issue #204 — earlier versions of the windsurf platform config omitted required frontmatter.

Solution: Update to the latest CLI: npx uipro-cli@latest init --ai windsurf --force.

Prevention: Track releases; this is fixed in current versions.

7. FAQ

Q: Do I need to install anything other than Node.js to install the skill?

No. npx uipro-cli init requires only Node.js 18+. The Python 3 dependency is for the runtime of the skill scripts inside your AI assistant — only matters once you start using the skill, not while installing it.

Q: Does the skill work offline?

The default init path is fully offline — all assets ship inside the npm package. The --legacy mode reaches out to GitHub releases. The update and versions commands also touch GitHub.

Q: Can I install for multiple AI tools at once?

Yes — npx uipro-cli init --ai all. The CLI iterates over the supported platform list and writes one skill folder per platform you've shown signs of using (presence of marker folders) or the full set if you pick all explicitly.

Q: What's the difference between --global and a per-project install?

--global writes to ~/.<tool>/skills/ui-ux-pro-max/ so every project on your machine sees the skill. A per-project install writes to ./.<tool>/skills/ui-ux-pro-max/ so only that project sees it. Some assistants merge both.

Q: How do I update?

npx uipro-cli@latest update fetches the latest version metadata and re-runs init with --force. You can also just re-run npx uipro-cli@latest init --force directly.

Q: How do I uninstall?

npx uipro-cli uninstall (per-project) or npx uipro-cli uninstall --global. The CLI shows what it removed and prompts for confirmation. See section 4 for the full per-platform folder map.

Q: Why does the skill ship Python scripts? Aren't AI assistants the ones doing the work?

The Python scripts are the deterministic search/composition layer. The AI calls them through its tool-call surface to do fast fuzzy matching over the 33 CSV files without burning tokens. The model decides what to ask for; the scripts return precise results.

Q: Does the skill connect to Figma?

Not at present. Issue #270 is open requesting Figma MCP support. The skill operates from text-based design data shipped with the package.

Q: Can I add my own styles or palettes?

Today, no — the package overwrites local data on every init/update. To customize, fork nextlevelbuilder/ui-ux-pro-max-skill, edit the CSVs in cli/assets/data/ (and mirror in src/ui-ux-pro-max/data/), and install from your fork via npx <your-fork> init.

Q: How do I integrate an existing design system into the skill?

Right now there's no first-class import. Issue #245 (closed) covered this; the practical workaround is to feed your tokens to the assistant in the same prompt: "Use the skill's principles, but my brand colors are X/Y/Z and my typeface is 'Inter Display'."

Q: Does it support every IDE / AI tool?

The 18 platforms listed in section 4 are the supported set as of v2.5.0. The full allow-list is enforced in cli/src/types/index.ts (AI_TYPES) and cli/src/utils/template.ts (AI_TO_PLATFORM). New platforms appear in releases — re-run npx uipro-cli@latest init to pick them up.

Q: What does the "skill activation phrase" look like?

There is no single magic phrase. The assistant decides when to load the skill based on design intent in your prompt. Words like "design", "UI", "UX", "layout", "color", "palette", "typography", "audit", "wireframe", or naming a stack ("React", "SwiftUI", "Tailwind") trigger it reliably.

Q: What if the assistant uses an old style or palette I don't like?

Push back in the same conversation: "use a different style — try minimal / brutalist / glassmorphic / ..." or "give me 5 alternatives". The skill ships 67 styles (styles.csv), so there's plenty of room to iterate.

Q: I see a .shared/ folder after install. What is that?

It's a backward-compatibility folder for platforms that previously installed via ZIP. Newer platforms include it as a no-op so uninstall removes the same set. Don't edit it; it'll be overwritten on next install.

Q: Are there alternatives if --legacy is failing me?

Use the default template path (just drop --legacy). It is the supported install method going forward and does not depend on any GitHub call.

Q: Where can I follow updates?

Latest releases live at https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/releases. The package is on npm as uipro-cli.