Ux Skill

English · [العربية](README.ar.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-TW.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [हिन्दी](README.hi.md) · [Bahasa Indonesia](README.id.md) · [Tiếng Việt](README.vi.md) · [ไทย](README.th.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Português](README.pt-BR.md) · [Italiano](README.it.md) · [Русский](README.ru.md) · [Türkçe](README.tr.md)

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](#quick-install) or see it live at uxskill.laithjunaidy.com.

Before: generic stock-photo SEO slop. After: real construction-photo hero under a dark scrim, editorial headline with an amber accent, quote form in the hero. Same AI coding tool, same prompt, different result when ux-skill supplies the constraints.

> 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

[](https://github.com/Laith0003/ux-skill/releases) [](https://www.python.org/downloads/) [](LICENSE) [](#the-17-ide-installer) [](#) [](data/brands/_index.json) [](data/components.json) [](data/anti-patterns.json) [](https://github.com/Laith0003/ux-skill/actions) [](data/motion-presets.json) [](https://github.com/Laith0003/ux-skill/stargazers) [](https://pypi.org/project/uxskill/) [](https://discord.gg/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](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](CHANGELOG.md#300--2026-05-28--the-brain).

Star history

[](https://star-history.com/#Laith0003/ux-skill&Date)

---

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](#the-brain--what-v30-is)
2. [Quick install](#quick-install)
3. [The numbers — live comparison vs the top 8 Claude UX skills](#the-numbers--live-comparison-vs-the-top-8-claude-ux-skills)
4. [Architecture — how the pieces fit](#architecture--how-the-pieces-fit)
5. [The 25 slash commands — detailed reference](#the-23-slash-commands--detailed-reference)
6. [The 5 sub-agents](#the-5-sub-agents)
7. [The 11 data manifests](#the-11-data-manifests)
8. [The 152 anti-AI-slop rules — the linter](#the-152-anti-ai-slop-rules--the-linter)
9. [The 160 brand DESIGN.md specs — by category](#the-160-brand-designmd-specs--by-category)
10. [MCP server — the asymmetric move](#mcp-server--the-asymmetric-move)
11. [The 17-IDE installer](#the-17-ide-installer)
12. [Use cases — concrete scenarios](#use-cases--concrete-scenarios)
13. [Compared to alternatives](#compared-to-alternatives)
14. [Roadmap](#roadmap)
15. [Contributing](#contributing)
16. [License, author, acknowledgments](#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

ux stats
# {
#   "version": "3.0.0-stable",
#   "counts": {
#     "styles": 84,
#     "palettes": 176,
#     "type-pairs": 70,
#     "components": 148,
#     "industries": 184,
#     "chart-types": 35,
#     "tech-stacks": 25,
#     "ux-guidelines": 112,
#     "motion-presets": 57,
#     "anti-patterns": 145,
#     "brands": 160
#   }
# }

If any count returns 0, the JSON file is missing — open an issue at github.com/Laith0003/ux-skill/issues.

---

The numbers — live comparison vs the top 8 Claude UX skills

Star counts last verified via gh api on 2026-05-28. ux-skill (Laith0003/ux-skill) is the newest entrant — we're tiny on awareness, deep on architecture. The comparison below is honest: where we lose, where we win.

| Plugin | Stars | Architecture | Slash commands | Linter (CI-safe) | Brand specs | Components | Motion presets | IDEs supported | |---|---:|---|---:|---|---:|---:|---:|---:| | nextlevelbuilder/ui-ux-pro-max-skill | 83,958 | Python BM25 + CSV, single skill | 1 | — | — | 0 | 0 | 18 | | nexu-io/open-design | 54,406 | Node.js + 19 skills + preview | 19 | — | — | 0 | 0 | 1 | | Leonxlnx/taste-skill | 25,202 | Bash + research-backed taste | 1 | — | — | 0 | 0 | 1 | | alchaincyf/huashu-design | 15,455 | Single 62 KB SKILL.md + scripts | 1 | — | — | 0 | 0 | 1 | | google-labs-code/stitch-skills | 5,762 | MCP-wired skill library | multi | — | — | 0 | 0 | 1 | | dominikmartn/nothing-design-skill | 2,391 | Single-aesthetic skill | 1 | — | — | 0 | 0 | 1 | | Nutlope/hallmark | 2,164 | Anti-slop design skill | 1 | — | — | 0 | 0 | 1 | | hamen/material-3-skill | 955 | MD3 components + audit | 1 | — | (MD3 only) | 0 | 0 | 1 | | Laith0003/ux-skill (ux-skill) | 14 | Python engine + 12 manifests + 25 commands + 5 sub-agents + CI linter | 22 | 152 regex rules | 160 | 148 | 57 | 17 |

Where we lose

• Awareness. They have hundreds of thousands of stars. We have 14. Star us — it's the cheapest way to help.
• Brand recognition. ui-ux-pro-max and open-design have a head start measured in months, not days.
• Marketing polish. They have screenshots, demo videos, and a discoverable landing page. We have a thorough README and a thin landing.

Where we win

• Component library: 148 documented components with anatomy, states, tokens used, and motion specs. None of the other 8 ship a component manifest.
• Motion presets: 57 stack-ready entries (Framer Motion, GSAP, CSS) with reduced-motion fallbacks. None of the others ship a motion manifest.
• Anti-pattern linter: 152 deterministic regex rules, runs in CI, exits non-zero on Critical/High. None of the others ship a deterministic linter.
• Brand specs: 160 real DESIGN.md specs (Apple, Stripe, Linear, Figma, Tesla, BMW, Notion, Spotify, Airbnb, Vercel, Supabase, Cursor, Raycast, Claude, and 96 more). None of the others ship a brand library.
• 17 IDEs supported: same engine, different glue per IDE.
• 25 slash commands: discovery, generation, audit, lint, polish, fix loop, case-study, workshop, copy, motion, a11y, dashboard, conductor — fully integrated.

Full table-by-table side-by-side at uxskill.laithjunaidy.com/compare.html.

---

Architecture — how the pieces fit

ux-skill (package name: uxskill)
│
├── data/                              The brain — queryable JSON manifests
│   ├── styles.json                    84 design styles + when/skip + tokens
│   ├── palettes.json                  176 palettes (light/dark, contrast verified)
│   ├── type-pairs.json                70 display × body × mono triplets
│   ├── components.json                148 components (anatomy, states, motion)
│   ├── industries.json                184 industry rules + audience signals
│   ├── chart-types.json               35 chart types (when/skip, encoding)
│   ├── tech-stacks

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Laith0003](https://github.com/Laith0003)
- **Source:** [Laith0003/ux-skill](https://github.com/Laith0003/ux-skill)
- **License:** MIT
- **Homepage:** https://uxskill.laithjunaidy.com

Install and usage instructions live in the source repository linked above.