ux-skill — the design intelligence engine for Claude Code, Cursor, and every other AI coding tool

A design-intelligence engine that makes AI-generated UI distinctive instead of generic. Drop it into any of 17 AI coding tools and your output stops reading as AI-built. Free, MIT, offline, no LLM.

pip install uxskill

Star ux-skill on GitHub if this is useful — it is the single cheapest way to help the project. New here? Start with the 60-second tour or see it live at uxskill.laithjunaidy.com.

> v3.1.0 — THE BRAIN, now brand-true + responsive. The strongest UX plugin for AI coding. A Python reasoning core with a deterministic 7-axis synthesizer, 12 queryable JSON manifests (84 styles, 176 palettes, 70 type pairings, 148 components, 184 industries, 35 chart types, 57 motion presets, 112 UX laws, 152 anti-pattern rules, 25 tech stacks, 160 brand specs), 25 slash commands, 5 sub-agents, 18 MCP tools, and a deterministic anti-AI-slop linter. Cross-IDE: ships into Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex, Kiro, Cline, Continue, Aider, Zed, JetBrains AI, Pieces, Tabby, Tabnine, CodeWhisperer, and Roo Cline.

> The brand name is ux-skill. The PyPI / npm package name stays uxskill. The GitHub repo lives at Laith0003/ux-skill.

Site: uxskill.laithjunaidy.com · Compare vs every Claude UX plugin: compare.html · GitHub: Laith0003/ux-skill · PyPI: uxskill · npm: uxskill

New in v3.1 — brand-true, responsive, alive

- Brand fidelity is enforced, not hoped. The primary color is read from the LOGO's pixels (not the most-painted CSS); default fonts are rejected for the logo's letterform style. The extracted brand travels recommend -> synthesize, and a hard floor in evaluate FAILS any output that drops the brand color/logo or ships no real imagery. Two-way interop with the open brand.md convention (render + ingest).
- Mobile-first, gated. New craft foundations (responsive.md, component-behaviors.md) plus a wrap-aware gate that fails on horizontal scroll, a wrapping nav/wordmark/button label, or an over-tall sticky header.
- The wow layer. The engine derives 2-3 coordinated signature moments per page — the "wow can only come from the user" doctrine is overturned.
- Sharper linter (152 rules): imagery-mandatory + icon-only detection, placeholder-token and 100vw rules; seeded picsum kept, random stripped.

Tests 310 passing. Offline. Deterministic. No LLM ever called. Full notes in CHANGELOG.md.

What's new in v3

- Brand specs become training data, not templates. The 160 brand specs are no longer a catalogue the recommender picks from — they're vocabulary the synthesizer distills from. Output is novel every call.
- 7-axis synthesizer (warmth, contrast, density, geometry, formality, motion, type_personality). Briefs map deterministically to axis values; axis values compile to fresh palette + type + spacing + radius + motion tokens.
- Three auto-dispatched modes — strict_brand (100% of one brand), brand_anchor (70% one brand + 30% axis-adapted siblings), pure_synthesis (no brand named — distill from 8 axis-matching exemplars).
- Decisions ledger drives the recommender. .ux/decisions.jsonl re-ranks candidates by past wins in the same (industry, ui_type) bucket. Cold-start safe. Counts only lint_score >= 80 + user_accepted = true decisions.
- Axis interaction matrix — explicit conflict resolution between competing axes (dense + corporate → 4px, airy + corporate → 12px, soft + playful → 18px radius). No more silent ad-hoc rules.
- /ux-evolve auto-loop — lint → polish → re-lint until score ≥ 90 or plateau or 5 rounds. Quality gate at 65.
- 3 new MCP tools (15 → 18): ux_synthesize, ux_decisions_query, ux_decisions_stats.
- Local stats dashboard — uxskill stats --html writes .ux/stats.html showing what YOUR install has learned. No telemetry, no global aggregate.
- 223 tests pass. Offline. Deterministic. No LLM ever called.

Full details in CHANGELOG.md.

Star history

---

What is ux-skill

ux-skill is a design intelligence engine for AI coding tools. It runs as a Python package (pip install uxskill), as a Claude Code plugin, and as a 17-IDE multi-installer. The engine ingests a project brief (industry, audience, tone, must-haves, forbidden moves, stack, region) and returns a complete recommended design system: style, palette, type pair, motion presets, components, brand exemplars to study, and the anti-pattern guardrails that must hold. The recommendation is deterministic — same input always produces the same output.

The plugin sits between you and the AI coding tool. When you ask Claude Code, Cursor, or any other AI assistant to "build a fintech landing page," the assistant typically improvises — and the result reads as AI-generated within five seconds (purple-to-blue gradients, three equal cards, Inter at display size, "John Doe" in testimonials, 300ms default transitions, centered hero, bouncing arrow CTAs). ux-skill replaces improvisation with structured constraints: you run /ux-discover to capture the brief, /ux-recommend to pick the system, /ux-design to generate the code, and /ux-lint to verify it passes the 152 deterministic anti-AI-slop rules before commit.

This README is the canonical reference. Every command, every sub-agent, every data manifest, every install path, every brand spec, every anti-pattern category — it's all documented here. If you're shopping for a Claude Code design plugin or comparing AI design tools for Cursor, Windsurf, or Codex, read this top to bottom and the compare.html side by side.

---

Table of contents

1. The Brain — what v3.0 is
2. Quick install
3. The numbers — live comparison vs the top 8 Claude UX skills
4. Architecture — how the pieces fit
5. The 25 slash commands — detailed reference
6. The 5 sub-agents
7. The 11 data manifests
8. The 152 anti-AI-slop rules — the linter
9. The 160 brand DESIGN.md specs — by category
10. MCP server — the asymmetric move
11. The 17-IDE installer
12. Use cases — concrete scenarios
13. Compared to alternatives
14. Roadmap
15. Contributing
16. License, author, acknowledgments

---

The Brain — what v3.0 is

v3.0.0 is the biggest architectural shift in ux-skill's history. The recommender no longer picks templates from a catalogue — the engine synthesizes a fresh design language per brief. Same brief always yields the same output (fully deterministic), but every distinct brief gets its own novel system. Brand specs aren't templates anymore; they're training data the engine learns the vocabulary from. The system has eyes on its own history, closes the feedback loop locally, and never calls an LLM.

The compiler is a deterministic 7-axis synthesizer — warmth, contrast, density, geometry, formality, motion, type_personality. Every brief maps to axis values; axis values compile to fresh palette + type + spacing + radius + motion tokens. Modular type scales pick their ratio from contrast (1.200 quiet / 1.250 balanced / 1.333 loud). Layout primitives are responsive by construction (auto-fit minmax(min(N, 100%), 1fr) + container queries). Broken layouts can't be emitted because they aren't representable.

There are three auto-dispatched modes: strict_brand (reference_brands=[stripe] strict=True → 100% Stripe tokens, fastest path); brand_anchor (reference_brands=[stripe] → 70% Stripe + 30% axis-adapted from 4 sibling brands); and pure_synthesis (no brand named → infinity space, 8 axis-matching exemplars distilled into a novel design language). Conflicting axes are resolved by a documented axis interaction matrix — dense + corporate compiles to 4px (density wins, Bloomberg-school), airy + corporate to 12px (formality wins, luxury), soft + playful to 18px radius, sharp + corporate to 2px. No silent ad-hoc rules in the implementation.

The decisions ledger (.ux/decisions.jsonl, schema _v: 1 locked) closes the feedback loop. The recommender now re-ranks candidates by past wins in the same (industry, ui_type) bucket. Cold-start safe — it skips below 3 priors. It only counts decisions with lint_score >= 80 AND user_accepted = true. Plus /ux-evolve runs lint → polish → re-lint until score ≥ 90 or plateau or 5 rounds, with a 65-score quality gate below which output is refused unless --force. The result: every install gets smarter on its own corpus, every run is reproducible across machines, and the engine stays fully offline.

---

Quick install

Three install paths. Pick the one that matches your environment.

Path 1 — Claude Code marketplace (canonical)

If you live in Claude Code, install via the plugin marketplace:

/plugin marketplace add Laith0003/ux-skill
/plugin install ux@ux-skill

That wires all 25 slash commands and 5 sub-agents into your Claude Code session. After install, run /ux-init to set up the per-project .ux/ state directory and verify the Python engine is reachable.

Path 2 — pip (universal)

If you live outside Claude Code (Cursor, Windsurf, CLI, CI), install the Python package:

pip install uxskill
uxskill init                       # auto-detects your IDE, installs the right artifact
uxskill stats                      # print manifest counts to verify install
uxskill lint .                     # run the linter against the current directory

The package exposes both ux and uxskill as CLI entry points — they're the same binary.

Path 3 — npx (no Python required)

If you don't want to manage Python directly, the npx wrapper bootstraps everything via pipx:

npx uxskill init                  # downloads pipx + uxskill on first run
npx uxskill recommend --industry=fintech-neobank --tone=warm --stack=nextjs-15-app-router

Verify install

```bash
ux stats