Skip to content

Home

Jump to bottom
Laith0003 edited this page Jun 3, 2026 · 4 revisions

ux-skill wiki

ux-skill is a design-intelligence engine for AI coding tools. It makes the UI those tools generate distinctive instead of generic. It is free, MIT-licensed, runs fully offline, and never calls an LLM.

pip install uxskill

This wiki is the practical companion to the README. The README is the exhaustive reference; the pages here are task-shaped:

  • Getting Started: install on your IDE, run the discover to recommend to design to lint loop, wire the linter into CI.
  • Anti-Patterns Reference: the 152 rules the linter enforces, by category and severity, with the reasoning and the fix for each tell.
  • FAQ: the questions people ask before installing, which IDEs, how it differs from a prompt or a token kit, what runs locally, how to contribute.

The problem it solves

Ask any AI coding assistant to "build a SaaS landing page" and you tend to get the same page. A purple-to-blue gradient on white. Three equal cards, each with an icon and a short paragraph. Inter set at display size. A centered hero with a bouncing-arrow call to action. "John Doe" in the testimonial. A 300ms default transition on everything.

None of those choices are wrong in isolation. The problem is that they are the defaults the model reaches for when no one constrained it, so every unconstrained output converges on the same look. A reader clocks it as machine-made in about five seconds. That recognizability is the slop, and it is a measurable set of patterns, not a vague vibe.

ux-skill replaces improvisation with structure. Instead of hoping the model has taste, you give it a system to work inside: a recommended style, palette, type pairing, motion set, and component shortlist derived from your brief, plus a deterministic linter that catches the known tells before they reach a commit.

How it fits together

The engine is a Python package that reads your brief and returns a complete design system. It ships three ways: as a pip install, as a Claude Code plugin via the marketplace, and through a multi-installer that targets 17 AI coding IDEs (Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex, Kiro, Cline, Continue, Aider, Zed, JetBrains AI, Pieces, Tabby, Tabnine, CodeWhisperer, and Roo Cline). The same engine sits behind all three; only the glue differs per IDE.

The reasoning core is a deterministic 7-axis synthesizer (warmth, contrast, density, geometry, formality, motion, type personality). Your brief maps to axis values; those values compile into fresh palette, type, spacing, radius, and motion tokens. Same brief in, same system out, every time, with no model call anywhere in the path.

Behind the synthesizer are 12 queryable JSON manifests:

Manifest Entries What it holds
Styles 84 Design styles with when-to-use, when-to-skip, and tokens
Palettes 176 Light and dark palettes, contrast-checked
Type pairs 70 Display, body, and mono triplets
Components 148 Anatomy, interaction states, tokens used, motion specs
Industries 184 Industry rules and audience signals
UX laws 112 Named laws (Hick, Fitts, Miller, and more)
Motion presets 57 Entry, exit, and hover presets with reduced-motion fallbacks
Chart types 35 When to use, when to skip, encoding guidance
Tech stacks 25 Next, Astro, SvelteKit, Blade, and others
Landing patterns varies Section recipes for landing-page composition
Page sequences varies Multi-page flow templates
Anti-patterns 152 The regex rules behind the linter

Alongside those twelve files sits a brands directory of 160 real DESIGN specs (Apple, Stripe, Linear, Figma, and 156 more), indexed for lookup. On top of the data sit 25 slash commands, 5 sub-agents, and an MCP server exposing 18 tools.

A typical session

/ux-discover     10-field intake: type, audience, goal, tone, must-haves, forbidden, brands, stack, region, metric
/ux-recommend    5 parallel searches across the manifests, merged into one system
/ux-design       generate the surface, grounded in the recommendation
/ux-lint         152 deterministic rules; non-zero exit on Critical or High

Discovery, recommendation, and linting are also available as plain CLI commands (ux discover, ux recommend, ux lint .). Code generation runs through the AI tool, so /ux-design is a slash command rather than a CLI one.

Discovery is a forcing function. It refuses vague answers like "modern" or "clean" and makes you commit to specifics, because specifics are what keep the output off the default path. Full walkthrough on the Getting Started page.

What it is not

  • Not a prompt. Prompts decay across a session and vary run to run. This is a deterministic engine with versioned data.
  • Not a hosted service. There is no account, no API key, no telemetry. Everything runs on your machine.
  • Not a component library you import. The components manifest is a specification the engine reasons over, not a runtime dependency you ship.
  • Not a replacement for a designer. It encodes known craft and catches known mistakes. Judgment is still yours.

Contributing and license

ux-skill is MIT-licensed. The most useful contributions are new brand specs, additional anti-pattern rules with a detection pattern and a fix, and reports of false positives in the linter. Open an issue or pull request at https://github.com/Laith0003/ux-skill. If the project is useful to you, a star is the cheapest way to help others find it.

Clone this wiki locally