# Ux Skill

> Design intelligence engine for AI coding tools (Claude Code, Cursor, Windsurf). Deterministic anti-AI-slop linter with 152 rules, 160 brand specs, a 7-axis synthesizer, an MCP server (18 tools), 25 commands, 17 IDEs. Offline, never calls an LLM. MIT.

- **Type:** MCP server
- **Install:** `agentstack add mcp-laith0003-ux-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Laith0003](https://agentstack.voostack.com/s/laith0003)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Laith0003](https://github.com/Laith0003)
- **Source:** https://github.com/Laith0003/ux-skill
- **Website:** https://uxskill.laithjunaidy.com

## Install

```sh
agentstack add mcp-laith0003-ux-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

```bash
pip install uxskill
```

**[Star ux-skill on GitHub](https://github.com/Laith0003/ux-skill)** 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](https://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`](https://github.com/Laith0003/ux-skill).

**Site:** [uxskill.laithjunaidy.com](https://uxskill.laithjunaidy.com) · **Compare vs every Claude UX plugin:** [compare.html](https://uxskill.laithjunaidy.com/compare.html) · **GitHub:** [Laith0003/ux-skill](https://github.com/Laith0003/ux-skill) · **PyPI:** [uxskill](https://pypi.org/project/uxskill/) · **npm:** [uxskill](https://www.npmjs.com/package/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](https://uxskill.laithjunaidy.com/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:

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

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

```bash
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
# {
#   "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](https://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](https://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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-laith0003-ux-skill
- Seller: https://agentstack.voostack.com/s/laith0003
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.