Skip to content

Getting Started

Jump to bottom
Laith0003 edited this page Jun 3, 2026 · 1 revision

Getting Started

This page takes you from nothing installed to a generated, linted surface in about fifteen minutes. It assumes you already use an AI coding tool. ux-skill sits between you and that tool; it does not replace it.

For the full reference, see the README. For the design rules the linter enforces, see Anti-Patterns Reference. For common questions, see the FAQ.

1. Install

Pick the path that matches where you work. All three install the same engine; the difference is the glue.

Path A, Claude Code marketplace

If you live in Claude Code, install through 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 the session. Then bootstrap the project:

/ux-init

Path B, pip (works everywhere)

For Cursor, Windsurf, a bare terminal, or CI:

pip install uxskill
uxskill init        # detects your IDE and installs the matching artifact

The package exposes two entry points, ux and uxskill. They are the same binary; use whichever reads better.

Path C, npx (no Python to manage)

npx uxskill init    # bootstraps pipx and uxskill on first run

2. Verify the install

Print the data inventory. This confirms the manifests loaded:

ux stats

You should see non-zero counts for every manifest, matching the v3.1.0 figures: 84 styles, 176 palettes, 70 type pairs, 148 components, 184 industries, 35 chart types, 25 tech stacks, 112 UX laws, 57 motion presets, 152 anti-patterns, 160 brand specs. If any count is zero, a JSON file failed to load; open an issue at https://github.com/Laith0003/ux-skill/issues with the output.

In Claude Code, the slash equivalent is /ux-stats.

3. Capture the brief with discovery

Everything downstream is grounded in a brief. Discovery is a 10-field intake, and it is deliberately strict: it rejects filler words like "modern" and "clean" and pushes you to name specifics, because specifics are what steer the output off the default path.

ux discover

The ten fields are: project type, audience, primary goal, tone, must-haves, forbidden moves, reference brands, stack, region, and success metric. The answers land in .ux/last-discovery.json so later commands can read them without asking again.

If you prefer non-interactive flags, skip straight to recommend (next step) and pass the brief there.

4. Recommend a system

This is the flagship command. It runs five lookups in parallel across the manifests and merges them into one design system.

ux recommend \
  --project-type=landing \
  --industry=fintech-neobank \
  --tone=warm --tone=editorial \
  --must-have=dark-mode --must-have=a11y-AA \
  --forbidden=purple-gradients --forbidden=brutalism \
  --stack=nextjs-15-app-router \
  --region=mena

The five parallel searches are: industry to recommended styles, style to palette and type and motion compatibility, tone crossed with must-haves to a palette filter, stack to component and motion-preset compatibility, and forbidden moves plus region to guardrails and a brand-exemplar shortlist. A deterministic merger ranks the candidates, resolves conflicts (a dark-mode must-have forces the palette mode, for example), and writes the result to .ux/last-recommendation.json.

The output is one document: a picked style, palette, and type pair; the top 5 motion presets; the top 12 components; the top 5 brand exemplars to study; all 152 anti-pattern guardrails active; and a rationale block that explains each pick. Because it is deterministic, the same brief on a teammate's machine produces the same system.

In Claude Code, run /ux-recommend; if you already ran /ux-discover, it reads the saved brief automatically.

5. Generate the surface

With a recommendation on file, generate code. Pick the command that matches the deliverable:

/ux-design build a fintech landing for a MENA neobank, warm editorial tone, dark-mode AA, no purple gradients
  • /ux-design for a full page or app shell.
  • /ux-component pricing-card-trio --brief="fintech, dark, monospace numbers" for a single component, generated with all four interaction states.
  • /ux-system for a complete starter design system (tokens, foundation docs, component contracts, dark-mode pairings) when the project has none.
  • /ux-dashboard for a data-dense surface, with tabular numerals and sparing motion rather than a marketing layout.

Generation dispatches the relevant sub-agent (frontend-engineer, motion-engineer, copy-writer, research-synthesizer, or design-system-architect) with creative direction pulled from the recommendation.

6. Lint before you commit

The linter is deterministic. It runs 152 regex rules against your code with no model call and exits non-zero on Critical or High findings, which makes it safe for a pre-commit hook or CI.

uxskill lint .

Each finding reports a file location, a rule id, a severity, and the evidence that triggered it. The linter reports; it does not edit. To act on findings, chain into a fix pass: /ux-polish --fix for a cosmetic pass, or /ux-fix to apply findings as atomic commits sorted by severity. The full rule set is documented on the Anti-Patterns Reference page.

7. Wire the linter into CI

Add the linter as a gate so regressions cannot merge. A GitHub Actions step:

- name: ux-lint
  run: bash bin/ux-lint.sh --ci --fail-on high

--fail-on high fails the job on any Critical or High finding while letting Medium and Low through as warnings. Tune the threshold to your tolerance. The same command works locally as a pre-commit hook.

The full command set

ux-skill ships 25 slash commands, grouped by job:

  • Bootstrap and inventory: /ux-init, /ux-stats, /ux-mcp
  • Discovery and recommendation: /ux-discover, /ux-recommend, /ux-frame
  • Generation: /ux-design, /ux-component, /ux-system, /ux-dashboard, /ux-motion, /ux-image-to-code
  • Audit and verify: /ux-lint, /ux-audit, /ux-a11y, /ux-critique, /ux-copy
  • Fix and polish: /ux-fix, /ux-polish, /ux-evolve
  • Research and workshop: /ux-research, /ux-workshop, /ux-case-study, /ux-expert
  • Conductor: /ux-next

Every command writes its result to a .ux/last-*.json file so commands chain: discover feeds recommend, recommend feeds design, design feeds lint, lint feeds fix. The full per-command spec, with triggers and when-to-skip notes, is in the README and at https://uxskill.laithjunaidy.com/commands.html.

Where to go next

Clone this wiki locally