Help

ux-design help

Explain the ux-design plugin to the user. This skill is the plugin's built-in guide: it answers "what can this do?" and "how do I use X?" without the user needing to read the docs tree.

How to respond

Look at what the user asked for (the $ARGUMENTS from /ux-help, or the topic named in natural language):

• No topic given → give the full overview below: the three modes, every skill, every command, the agent, and the bundled tools, each in one line, then point to the docs and the natural next step.
• A specific topic given (a skill, command, agent, tool, or concept like "tokens", "accessibility", "contrast") → resolve it to the matching item(s) and explain just that: what it does, when it triggers, how to invoke it (both the Claude Code command/skill and the Codex /ux-design:<skill> form), and what it produces. Then read that item's detailed doc under docs/ (or its SKILL.md) and fold in the specifics. If the topic is ambiguous, list the close matches and ask which they meant.

Keep it skimmable: lead with a one-line answer, then the detail. Don't dump file contents — summarize and link.

Full overview (use when no topic is named)

ux-design helps you guide, measure, and implement UX best practices, across three modes:

• Guide — explain the right pattern while you work.
• Measure — score what exists, qualitatively and quantitatively.
• Implement — scaffold best practices into your codebase, adapted to its stack.

Skills (the cross-agent surface)

Skill	Mode	What it does
ux-foundations	Implement	Orchestrates a full UX baseline (tokens + accessible primitives + a11y lint + metrics + UX-CHECKLIST.md); owns the shared stack-detection convention.
ux-onboarding	Guide	Guided, part-by-part walkthrough of an existing project's UX/design patterns, ending in a reimplement-a-recent-change exercise.
ux-audit	Measure / Guide	Nielsen's 10 heuristics + IA + task-flow review → scored report.
accessibility-audit	Measure	WCAG 2.2 AA, per-criterion severity scoring; bundled zero-dep contrast checker.
ux-metrics	Measure	Core Web Vitals, Lighthouse/axe scores, analytics taxonomy, SUS survey scoring.
design-tokens	Implement	Scaffold/refactor tokens (color, type, space, radius, shadow, motion); migrate hardcoded values.
accessible-components	Implement	Accessible WAI-ARIA patterns (dialog, tabs, menu, combobox, disclosure, fields, tooltip) + a11y linting.
interaction-feedback	Implement / Guide	Empty/loading/error/success states, aria-live toasts, inline validation, optimistic UI, reduced-motion.
ux-copy	Guide	Microcopy, error messages, empty states, CTAs, voice & tone.
help	—	This guide.

Skills trigger automatically from natural language — you rarely name them.

Commands (Claude Code conveniences)

• /ux-audit [path\|url] → runs ux-audit + accessibility-audit → one consolidated scored report.
• /ux-bootstrap → runs ux-foundations (tokens, primitives, a11y lint, metrics, checklist).
• /ux-onboarding [path\|area] → guided walkthrough of the project's existing UX/design patterns.
• /ux-review [file\|url] → launches the ux-reviewer agent for a fast scored review of one artifact.
• /ux-help [topic] → this help.

Agent

• ux-reviewer — scores a single component or screen across four lenses (usability heuristics, accessibility, visual hierarchy, interaction feedback), from code, a screenshot, or a live page. Invoked by /ux-review, or ask to "review this component".

Bundled tools (zero dependencies, run standalone)

node skills/accessibility-audit/scripts/contrast.mjs "#777" "#ffffff"
node skills/design-tokens/scripts/type-scale.mjs 16 1.25
node skills/ux-metrics/scripts/sus-score.mjs 4 2 5 1 5 1 4 2 5 1

Claude Code & Codex

The skills are the shared, cross-agent surface. On Codex they're exposed as slash commands (/ux-design:ux-audit, /ux-design:help, …) and trigger from natural language on either agent. The /ux-* commands and the ux-reviewer agent are Claude-Code conveniences over those skills; on Codex, invoke the skills directly.

Where to go next

• Full per-skill guides: docs/README.md and the per-skill pages in docs/.
• Plugin overview and install: README.md.
• A typical loop: /ux-onboarding (understand) → /ux-bootstrap (lay foundation) → build with the implement skills → /ux-audit (measure) → /ux-review (spot-check).

Resolving a named topic

Map the user's word to the right item before explaining:

• "tokens", "design system", "colors", "type scale", "spacing" → design-tokens (+ type-scale.mjs).
• "accessibility", "a11y", "wcag", "contrast", "screen reader" → accessibility-audit (+ contrast.mjs); for building accessible UI, accessible-components.
• "audit", "heuristics", "usability" → ux-audit (and /ux-audit which also runs accessibility-audit).
• "metrics", "web vitals", "sus", "lighthouse" → ux-metrics (+ sus-score.mjs).
• "states", "loading", "error", "toast", "feedback", "validation" → interaction-feedback.
• "copy", "microcopy", "wording", "cta", "voice", "tone" → ux-copy.
• "bootstrap", "set up", "scaffold", "foundation", "baseline" → ux-foundations / /ux-bootstrap.
• "onboard", "walk me through", "learn this project" → ux-onboarding / /ux-onboarding.
• "review this component/screen" → ux-reviewer / /ux-review.

Then open the matching docs/<item>.md (or skills/<item>/SKILL.md) and explain from it.