v3.0 — THE BRAIN · 2026-05-28 · ~5 min read

ux-skill v3.0 in five minutes.

Install. Synthesize a fresh design language from a brief. Run the evolve loop. Check what your install has learned. Ship. The whole flow, end to end, in a single coffee.

What you'll have at the end

A working v3.0 install of ux-skill
A complete synthesized design language for one brief (palette + type + spacing + radius + motion)
A linted output with a 0-100 quality score
The evolve loop run once
A local stats dashboard showing what your install has learned

Minute 1 — Install

step 1 / 6

# Python path (works in any IDE / terminal)
pip install uxskill

# OR npm path (npx wrapper, same backend)
npm install -g uxskill

Verify:

uxskill version
# → 3.0.0

Minute 2 — Initialize

step 2 / 6

cd your-project
uxskill init

This auto-detects your IDE (Claude Code, Cursor, Windsurf, Codex, Gemini CLI, JetBrains AI, Pieces, Continue, Cline, Aider, Zed, Kiro, Roo Cline, Tabby, Tabnine, CodeWhisperer, GitHub Copilot) and writes the right configuration file. It also creates .ux/ for the decisions ledger.

Verify the install:

uxskill stats
# → version: 3.0.0, counts: {styles: 84, palettes: 176, type-pairs: 70,
#   components: 148, industries: 184, ...}

Minute 3 — Synthesize a design language

step 3 / 6

This is the v3.0 flagship. Give the engine a brief and it computes a complete design language — palette, type pair, spacing scale, radius scale, motion timing — from 7 axes derived from your brief.

uxskill synthesize \
  --industry fintech-payments \
  --tone bold --tone serious

You'll get back JSON like:

{
  "mode": "pure_synthesis",
  "axes": {
    "warmth": 0.35,
    "contrast": 0.80,
    "density": 0.6,
    "geometry": 0.4,
    "formality": 0.95,
    "motion": 0.55,
    "type_personality": 0.4
  },
  "palette": {
    "canvas": "#0a1014",
    "ink": "#f6f8fa",
    "body": "#9ca3af",
    "primary": "#3b82f6",
    "muted": "#6b7280",
    "hairline": "rgba(255,255,255,0.08)"
  },
  "type_pair": {
    "display": "Inter Tight",
    "body": "Inter",
    "mono": "JetBrains Mono"
  },
  "spacing": { "base": 4, "scale": [4, 8, 12, 20, 32, 52, 84] },
  "radius": { "base_px": 4, "sm": 2, "md": 4, "lg": 6, "xl": 10, "pill": 999 },
  "motion": { "base_ms": 245, "curve_name": "ease-cinema" }
}

This output is deterministic — same brief always produces the same JSON. Reproducible across machines.

Try a brand anchor:

uxskill synthesize --brand stripe \
  --industry healthcare \
  --tone warm --tone trustworthy
# → mode: "brand_anchor" — Stripe-flavored, healthcare-adapted

Try strict brand:

uxskill synthesize --brand stripe --strict
# → mode: "strict_brand" — 100% Stripe tokens, no synthesis

Minute 4 — Lint with a 0-100 score

step 4 / 6

v3.0's linter returns a quality score in addition to findings. 100 = clean. Below 65 trips the quality gate.

# Plain run — JSON output with findings + score
uxskill lint .

# Just the score (useful in shell pipes)
uxskill lint . --score-only
# → 92

# CI mode — exit code 1 if findings >= --threshold severity
uxskill lint . --threshold high
echo $?  # 0 = clean enough; 1 = fail

Each call writes one line to .ux/decisions.jsonl automatically. The recommender will consult this on the next call.

Disable logging for a single call:

uxskill lint . --no-log
# or
UXSKILL_NO_LOG=1 uxskill lint .

Minute 5 — Run the evolve loop

step 5 / 6

Given a generated HTML file, the evolve loop auto-iterates lint → polish → re-lint until score ≥ 90 or plateau or 5 rounds.

uxskill evolve docs/hero.html --css docs/hero.css

# Output:
# EVOLVING: docs/hero.html (initial score: 72)
# Round 1: composite=72 → applied: strip_inline_styles, normalize_spacing
# Round 2: composite=84 (Δ +12) → applied: replace_generic_ctas, fontweight_numeric
# Round 3: composite=89 (Δ +5) → applied: swap_placeholder_urls
# Round 4: composite=91 → target_hit. Stop.
#
# EVOLVE COMPLETE: 72 → 91 (target_hit, 4 rounds)
# artifact:     docs/hero.evolved.html
# evaluation:   .ux/last-evolve.json
# ledger entry: .ux/decisions.jsonl (+1)

If the final score is below 65, the loop refuses to ship unless you pass --force:

# Force-ship below quality gate
uxskill evolve  --force

Minute 6 — See what your install has learned

step 6 / 6

uxskill stats --html
# → writes .ux/stats.html

open .ux/stats.html
# Opens a single-file dashboard in your browser showing:
# - Total decisions logged
# - Lint score median / mean
# - By command / by industry / by mode breakdown
# - Top brands picked
# - Acceptance rate

This is YOUR install's data. No telemetry. No global aggregate. It just shows what YOUR work has produced.

What's happening behind the scenes

Synthesize ran the 7-axis derivation, distilled vocabulary from 8 axis-matching brand specs, mixed weighted by axis position. No LLM call.
Lint ran 145 deterministic regex rules in <50ms. Each call wrote one JSONL line.
Evolve ran the 6 idempotent polish passes (strip inline styles, normalize spacing, replace generic CTAs, swap placeholder URLs, strip Lorem, fontweight numeric).
Stats aggregated the JSONL ledger into the HTML dashboard.

After 3+ accepted+clean decisions in any (industry, ui_type) bucket, the recommender starts re-ranking by past wins. Your install gets smarter for the kinds of products you ship.

One-line everything (for your shell history)

pip install uxskill && uxskill init && \
  uxskill synthesize --industry fintech-payments --tone bold > design.json && \
  uxskill lint . --score-only && \
  uxskill stats --html && open .ux/stats.html