# 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

```bash
npx uipro-cli init
```

Expected output (auto-detected Claude Code):

```text
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`:

```bash
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.

```text
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

| Component | Required | Why |
|-----------|----------|-----|
| Node.js | `>=18` | Runtime for the `uipro` CLI (declared in dependencies for `commander@^12.1.0`, `chalk@^5.3.0`, `ora@^8.1.1`, `prompts@^2.4.2`) |
| npm / bun / npx | one of | To invoke the CLI; `npx` is the path used in this guide |
| Python 3 | runtime | The skill's `core.py`, `design_system.py`, and `search.py` scripts run on the user's local Python whenever the AI agent invokes them post-install |
| Disk space | ~5 MB per platform | CSV reference data + Python scripts + markdown templates |
| Internet | optional | Only the `--legacy` mode and the `update` / `versions` subcommands hit GitHub; the default template path works fully offline from the bundled assets in the npm package |

### 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.

```bash
# In your project directory
npx uipro-cli init
```

If you prefer a permanent install:

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

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

```bash
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:

```text
.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

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

Expected output:

```text
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)

| Error | Likely cause | Fix |
|---|---|---|
| `error: unknown option '--global'` | Stale npx-cached binary (issue #215) | `npx clear-npx-cache` then `npx uipro-cli@latest init --global` |
| `env: node: No such file or directory` | Node is not on `PATH` (issue #50) | Reinstall Node 18+, restart shell |
| `GitHub API rate limit exceeded. Resets at <time>` | `--legacy` mode hit GitHub anonymous limit | Wait until reset, or set `GITHUB_TOKEN`, or drop `--legacy` |
| `GitHub API rate limit exceeded (429 Too Many Requests)` | Same as above (HTTP 429 path) | Same fix |
| `Failed to fetch latest release: 403 ...` | GitHub auth/rate-limit edge case | Drop `--legacy`, or wait, or supply a token |
| `Failed to fetch releases: <status>` | Transient GitHub fault during `versions` | Retry; not blocking — `init` works without it |
| `Failed to download: <status>` | Asset URL 404 (release without zip) | Drop `--legacy` to use templates instead |
| `No ZIP asset found in latest release` | Release is template-only | Drop `--legacy`; templates are the supported default |
| `Invalid AI type: <foo>` | Misspelled `--ai <type>` | Pick from the allow-list (see section 1 or run with no flag for the picker) |
| `Failed to extract zip: ...` | PowerShell or `unzip` missing on host | Install `unzip` (Linux/macOS) or run on a host with PowerShell (Windows); or drop `--legacy` |
| `Unknown AI type: <foo>` | Internal template loader received an unmapped `aiType` | Same as above — check spelling against the allow-list |

> [!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

| Flag | Applies to | Default | Effect |
|---|---|---|---|
| `-a, --ai <type>` | `init`, `update`, `uninstall` | auto-detect | Pick the AI assistant type explicitly |
| `-f, --force` | `init` | off | Overwrite existing skill files |
| `-o, --offline` | `init` | off | Skip the GitHub call inside `--legacy` mode (no effect on the default template path) |
| `-g, --global` | `init`, `uninstall` | off | Install/remove under your home directory (`~/`) instead of the current project |

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.

```bash
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:

```bash
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.

| Category | File | What it contains |
|---|---|---|
| App interface patterns | `data/app-interface.csv` | Screen-level layout patterns (dashboard, list, detail, settings) |
| Charts & visualization | `data/charts.csv` | 25 chart types with use-cases and pitfalls |
| Color palettes | `data/colors.csv` | 161 curated palettes with mood and industry tags |
| General design rules | `data/design.csv` | Cross-cutting design principles |
| Draft / wireframe stages | `data/draft.csv` | What belongs in early vs. polished mockups |
| Google Fonts catalog | `data/google-fonts.csv` | 57 font pairings (display + body) with use-cases |
| Icon systems | `data/icons.csv` | Icon set guidance |
| Landing page patterns | `data/landing.csv` | Landing-page section orderings and hero patterns |
| Product archetypes | `data/products.csv` | Industry-specific product types |
| React performance | `data/react-performance.csv` | React-specific perf rules (memoization, virtualization, code-split) |
| UI styles | `data/styles.csv` | 67 styles (minimal, neumorphic, brutalist, glassmorphic, etc.) |
| Typography rules | `data/typography.csv` | Hierarchy, scale, line-height conventions |
| UI reasoning | `data/ui-reasoning.csv` | Why a style fits an industry |
| UX guidelines | `data/ux-guidelines.csv` | 99 UX heuristics |

### 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.

| Stack | File |
|---|---|
| Angular | `data/stacks/angular.csv` |
| Astro | `data/stacks/astro.csv` |
| Flutter | `data/stacks/flutter.csv` |
| HTML + Tailwind | `data/stacks/html-tailwind.csv` |
| Jetpack Compose | `data/stacks/jetpack-compose.csv` |
| Laravel | `data/stacks/laravel.csv` |
| Next.js | `data/stacks/nextjs.csv` |
| Nuxt UI | `data/stacks/nuxt-ui.csv` |
| Nuxt.js | `data/stacks/nuxtjs.csv` |
| React | `data/stacks/react.csv` |
| React Native | `data/stacks/react-native.csv` |
| shadcn/ui | `data/stacks/shadcn.csv` |
| Svelte | `data/stacks/svelte.csv` |
| SwiftUI | `data/stacks/swiftui.csv` |
| Three.js | `data/stacks/threejs.csv` |
| Vue | `data/stacks/vue.csv` |

### 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.

| Script | Role |
|---|---|
| `scripts/core.py` | Shared CSV loading, normalization, and tag matching |
| `scripts/design_system.py` | Composes a coherent design system from style + palette + typography choices |
| `scripts/search.py` | Fuzzy search over any CSV by tag, industry, mood, or free text |

### 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`.

| Platform | Detected via | Install root |
|---|---|---|
| Claude Code | `.claude/` | `.claude/` |
| Cursor | `.cursor/` | `.cursor/` + `.shared/` |
| Windsurf | `.windsurf/` | `.windsurf/` + `.shared/` |
| Antigravity | `.agents/` or `.agent/` | `.agents/` + `.shared/` |
| GitHub Copilot | `.github/` | `.github/` + `.shared/` |
| Kiro | `.kiro/` | `.kiro/` + `.shared/` |
| Codex | `.codex/` | `.codex/` |
| RooCode | `.roo/` | `.roo/` + `.shared/` |
| Qoder | `.qoder/` | `.qoder/` + `.shared/` |
| Gemini CLI | `.gemini/` | `.gemini/` + `.shared/` |
| Trae | `.trae/` | `.trae/` + `.shared/` |
| OpenCode | `.opencode/` | `.opencode/` + `.shared/` |
| Continue | `.continue/` | `.continue/` |
| CodeBuddy | `.codebuddy/` | `.codebuddy/` |
| Droid (Factory) | `.factory/` | `.factory/` |
| KiloCode | `.kilocode/` | `.kilocode/` + `.shared/` |
| Warp | `.warp/` | `.warp/` + `.shared/` |
| Augment | `.augment/` | `.augment/` + `.shared/` |

> [!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:

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

   ```text
   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:

   ```text
   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:

   ```text
   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:

   ```text
   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:

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

```text
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:

```text
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`.

---

_Generated April 2026 from nextlevelbuilder/ui-ux-pro-max-skill at b7e3af8. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._