User Guide

Getting Started

What is UX-Master?

UX-Master is an AI-powered design intelligence platform that helps you:

• ✅ Validate designs against 37 Design Tests
• ✅ Generate complete design systems in seconds
• ✅ Extract design tokens from any website
• ✅ Apply 48 UX Laws for psychology-driven design

Who is it for?

• Designers - Validate designs before handoff
• Developers - Ensure UI meets UX standards
• Product Managers - Quick design quality checks
• Teams - Maintain consistency across products

Installation

Prerequisites

• Python 3.10+
• pip or uv
• (Optional) Node.js for Figma plugin development

Install UX-Master CLI

pip install uxmaster-cli

Or with uv (faster):

uv pip install uxmaster-cli

Verify Installation

uxm --version
# Should print: uxmaster, version 2.0.0

CLI Usage

Command Overview

uxm [command] [arguments] [options]

Common Workflows

Workflow 1: Design System from Scratch

# Generate design system
uxm search "e-commerce mobile app" --design-system -p "ShopApp"

# Save to file
uxm search "e-commerce mobile app" --design-system --format markdown --output design-system.md

Workflow 2: Validate Existing Design

# Extract from website
uxm extract https://competitor.com --output competitor.json

# Validate extracted design
uxm validate competitor.json --suite all --format html --output report.html

# Open report
open report.html

Figma Plugin

Installation

1. Open Figma Desktop
2. Go to Plugins → Development → Import Plugin from Manifest
3. Select mcp/integrations/figma/plugin/manifest.json

Generate Design System

1. Open plugin from Figma menu
2. Click ✨ Generate tab
3. Describe your project:

A fintech dashboard with dark mode, modern glassmorphism style

4. Click ✨ Generate Magic
5. Wait 2-3 seconds
6. Review generated tokens
7. Click Apply to Figma to create Variables

Understanding Validation Results

Score Interpretation

Issue Severity

• 🔴 Critical - Must fix before shipping
• 🟠 High - Should fix for good UX
• 🟡 Medium - Fix if time permits
• 🟢 Low - Nice to have

MCP Server

What is MCP?

Model Context Protocol (MCP) allows AI assistants like Claude, Cursor, and VS Code to use UX-Master tools directly.

Starting the Server

# Default port 3000
uxm mcp start

# Custom port
uxm mcp start --port 8080

# With Figma integration
uxm mcp start --figma-token YOUR_TOKEN

Using with Claude Code

Once installed (uxm init --ai claude), Claude can:

You: Create a landing page for my SaaS

Claude: I'll design a landing page for you. Let me check the UX guidelines first...

[Claude uses UX-Master internally]

Claude: Based on UX-Master's recommendations, here's your design:
- Hero section with clear value proposition
- Primary CTA in contrasting color
- Social proof above the fold
- Form limited to 3 fields

I've applied Fitts's Law (44px touch targets) and Hick's Law 
(limited choices) to optimize conversions.

Validation

Test Suites Explained

All Tests (37)

Complete validation across all categories:

• Mobile (7 tests)
• Landing Page (6 tests)
• Dashboard (6 tests)
• Typography (4 tests)
• Color (4 tests)
• Layout (4 tests)
• Accessibility (5 tests)
• Interaction (5 tests)

Validation Tests Reference

Design System Generation

From Description

uxm search "dark mode fintech dashboard with glassmorphism" --design-system

From Website

# Extract existing design
uxm extract https://linear.app --output linear.json

# Generate based on extracted style
uxm search "similar to linear.app but for healthcare" --design-system

Output Formats

Markdown (Human-readable)

uxm search "fintech dashboard" --design-system --format markdown --output design.md

JSON (Machine-readable)

uxm search "fintech dashboard" --design-system --format json --output tokens.json

Best Practices

Design Validation Workflow

1. Design Phase - Create initial design in Figma, run validation every 30 minutes, fix critical issues immediately
2. Before Handoff - Run full validation suite, score should be >= 80, generate validation report
3. During Development - Validate components as built, run CI/CD validation checks, monitor regression
4. Before Launch - Final validation pass, document exceptions, archive reports

Validation Frequency

Troubleshooting

Common Issues

Issue: command not found: uxm

# Check Python path
which python3

# Reinstall with --user
pip install --user uxmaster-cli

# Or use full path
python3 -m uxmaster --help

Issue: MCP server not running

# Start server
uxm mcp start

# Check if running
curl http://localhost:3000/health

# Check port availability
lsof -i :3000

Getting Help

• Check documentation: uxm docs
• Verbose output: uxm validate file.html -v
• Community Discord: discord.gg/uxmaster
• GitHub Issues: github.com/uxmaster/ux-master/issues