uxskill
Star on GitHub
Language
English 简体中文 繁體中文 日本語 한국어 हिन्दी Bahasa Indonesia Tiếng Việt ไทย العربية Español Français Deutsch Português Русский Türkçe Italiano

## 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

## Next reads

- The v3.0 launch · The Brain
- The 7 axes explained
- Brand specs are training data, not templates
- What a closed loop actually means
- Wiki · v3-The-Brain
- Wiki · Migration v2 → v3