UX Toolkit

AI-powered UI/UX review toolkit with skills, agents, and commands for OpenCode and other AI coding assistants.

Features

• 25 Skills: Comprehensive UX knowledge from heuristics to game UI patterns
• 18 Agents: Specialized reviewers for different page types (list, detail, editor, game, replay, cards)
• Commands: Quick-trigger UX workflows
• Severity Weights: All checklists categorized as Critical/Major/Minor
• Parallel Review: Dispatch multiple specialized agents simultaneously

Quick Start

Install globally for OpenCode

npx ux-toolkit install --global

This installs skills, agents, and commands to ~/.config/opencode/.

Install for a specific project

npx ux-toolkit install --project

This installs to .opencode/ in your current directory.

What's Included

Skills (25)

Core UX

Skill	Description
ux-heuristics	Nielsen's 10 usability heuristics with evaluation methodology
wcag-accessibility	WCAG 2.2 compliance checklist and ARIA patterns
visual-design-system	Layout, typography, color theory, spacing systems
interaction-patterns	Micro-interactions, loading states, feedback mechanisms
mobile-responsive-ux	Touch targets, gestures, responsive patterns

Page Structure

Skill	Description
page-structure-patterns	Base requirements for page states, layout, and structure
list-page-patterns	Filters, sorting, pagination, and grid/table displays
detail-page-patterns	Headers, tabs, multi-column layouts, related data
navigation-patterns	Sidebar, mobile drawer, breadcrumbs, app shell

Components

Skill	Description
modal-patterns	Confirmation, edit, selector, and wizard modals
form-patterns	Validation, field layouts, multi-step wizards
data-density-patterns	Dense layouts, z-index, overflow, readability
toast-notification-patterns	Toast types, timing, queuing, accessibility

Interactions

Skill	Description
keyboard-shortcuts-patterns	Command palette (Cmd+K), shortcut registry
drag-drop-patterns	Drag preview, drop zones, keyboard alternatives

Editor/Workspace

Skill	Description
editor-workspace-patterns	Multi-tab editors, dirty state, undo/redo, auto-save
comparison-patterns	Side-by-side comparison, diff highlighting
split-panel-patterns	Resizable panels, dividers, collapsible sidebars

Game/Interactive

Skill	Description
canvas-grid-patterns	Hex grids, tactical maps, pan/zoom, tokens, coordinates
turn-based-ui-patterns	Phase banners, turn indicators, action bars, game state
playback-replay-patterns	VCR controls, timeline scrubbing, speed selection
status-visualization-patterns	Health bars, progress meters, heat gauges, pip displays

Data Display

Skill	Description
info-card-patterns	Compact/standard/expanded cards, stat blocks, badges
event-timeline-patterns	Activity feeds, audit logs, chronological events

Framework

Skill	Description
react-ux-patterns	React/Next.js specific UX patterns

Agents (18)

General Purpose

Agent	Mode	Description
ux-auditor	Analysis	Full UX audit against heuristics (read-only)
ux-engineer	Fix	UX analysis + implements fixes
accessibility-auditor	Analysis	WCAG 2.2 compliance review (read-only)
accessibility-engineer	Fix	Accessibility fixes
visual-reviewer	Analysis	Design system consistency check
interaction-reviewer	Analysis	Micro-interactions and feedback review

Specialized Page Reviewers

Agent	Mode	Description
list-page-reviewer	Analysis	List/browse page UX review
detail-page-reviewer	Analysis	Detail/entity page UX review
navigation-reviewer	Analysis	Navigation and routing review
form-reviewer	Analysis	Form and input UX review
density-reviewer	Analysis	Data density and layout review

Advanced Specialized Reviewers

Agent	Mode	Description
editor-reviewer	Analysis	Editor/workspace UI with multi-tab, drag-drop
comparison-reviewer	Analysis	Side-by-side comparison and diff UIs
settings-reviewer	Analysis	Settings, preferences, and configuration pages

Game & Interactive Reviewers

Agent	Mode	Description
game-ui-reviewer	Analysis	Tactical maps, turn-based combat, hex grids, status displays
replay-reviewer	Analysis	Playback controls, timeline scrubbing, event feeds
card-reviewer	Analysis	Info cards, stat blocks, entity displays with density levels
panel-reviewer	Analysis	Resizable panels, collapsible sidebars, split views

Commands

Command	Description
/ux-audit	Comprehensive UX audit
/ux-a11y-check	Quick accessibility scan
/ux-design-review	Visual consistency check
/ux-screenshot-review	Visual review from screenshot

Usage Examples

In OpenCode

# Run a full UX audit
/ux-audit src/components/Button.tsx

# Check accessibility
/ux-a11y-check src/pages/index.tsx

# Invoke agent directly
@ux-auditor Review the login flow for usability issues

# Use specialized reviewer for a list page
@list-page-reviewer Review /users page against list-page-patterns

# Use editor reviewer for complex workspace
@editor-reviewer Review the Customizer page for editor patterns

# Use game reviewer for tactical interfaces
@game-ui-reviewer Review the combat screen for grid and turn-based patterns

# Use replay reviewer for playback interfaces
@replay-reviewer Review the game replay viewer

Parallel Review (Recommended)

For comprehensive review, dispatch multiple specialized agents:

# In your AI assistant, dispatch these in parallel:
@list-page-reviewer Review /items page
@navigation-reviewer Review sidebar navigation  
@density-reviewer Review dashboard layout

With Playwright MCP

For visual inspection capabilities, add Playwright MCP to your config:

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "@playwright/mcp@latest", "--caps", "vision"],
      "enabled": true
    }
  }
}

Severity Weights

All audit checklists use severity weights to help prioritize fixes:

Severity	Meaning	Action
[CRITICAL]	Accessibility violation, data loss risk, users blocked	Must fix before release
[MAJOR]	Significant UX problems, confusion, inefficiency	Should fix soon
[MINOR]	Polish items, nice-to-have improvements	Fix when time permits

Manual Installation

If you prefer to install manually:

# Clone the repo
git clone https://github.com/swiggityswerve/ux-toolkit.git

# Copy to global config
cp -r ux-toolkit/skills/* ~/.config/opencode/skills/
cp -r ux-toolkit/agents/* ~/.config/opencode/agents/
cp -r ux-toolkit/commands/* ~/.config/opencode/commands/

Customization

Override agent permissions

In your opencode.json:

{
  "agent": {
    "ux-engineer": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

Add custom skills

Create additional skills in ~/.config/opencode/skills/my-skill/SKILL.md.

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

License

MIT