# UI UX Design

> Use when designing user-facing surfaces — information architecture, user/data flows, screens or command surfaces, design-system baseline. Triggers — new web page, mobile screen, CLI command.

- Skill: `muxammadmamajonov/ui-ux-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add muxammadmamajonov/ui-ux-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/muxammadmamajonov/ui-ux-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: muxammadmamajonov (https://skillmd.com/u/muxammadmamajonov)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/muxammadmamajonov/ui-ux-design

---


# UI / UX & Interaction Design

## When to use
- A spec or feature is approved and a human-facing or machine-facing surface must be designed before build.
- You are adding a new screen, view, command, endpoint shape, notification, or device interaction.
- Usability, accessibility, or consistency problems are reported and a redesign is needed.
- The project lacks a shared design baseline (tokens, components, interaction patterns) and drift is appearing.

"UI" here is broad: GUI screens, CLI/TUI command surfaces, conversational/agent turns, API request/response ergonomics, dashboards, and embedded/IoT displays all have an interaction layer worth designing.

## Workflow
1. **Restate the job-to-be-done.** From the spec, write one sentence per primary user (or consuming system) describing the outcome they need. Reference the founder interview and `.claude/templates/product-spec.md`. If a primary user is unclear, ask the user — do not invent personas.
2. **Map information architecture.** List the top-level entities, their relationships, and how a user navigates between them. For non-GUI projects this is the command/resource hierarchy or the object model an API exposes. Produce a tree or sitemap.
3. **Design the critical flows.** For each top-3 task, write the happy path as numbered steps, then enumerate the empty, loading, error, partial-permission, and offline states. A flow is not done until every state is named.
4. **Sketch screens / surfaces low-fidelity first.** Lay out each surface as labeled regions (header, primary action, content, secondary). Decide the single primary action per surface. Keep it text/wireframe level — do not pick colors or pixel values yet.
5. **Establish the design-system baseline.** Define tokens once: spacing scale, type scale, color roles (not raw hex scattered everywhere), radius, elevation, motion durations. Define core components (button, input, list, card, dialog, toast, empty-state) with their states. Record this in `.claude/templates/architecture.md` or a dedicated design-system doc.
6. **Specify interaction & accessibility rules.** Keyboard order, focus management, hit-target sizes, contrast ratios, error-recovery, copy tone. For CLI: flag conventions, `--help` output, exit codes, machine-readable output mode. For APIs: consistent naming, pagination, error envelope.
7. **Validate cheaply.** Walk each flow against the spec's acceptance criteria. Run a heuristic pass (see Standards). If feasible, do a 3–5 person hallway test or a quick task walkthrough before committing to build.
8. **Hand off.** Produce the artifact described in Output format, link it from the spec, and flag the build phases that implement it.

## Standards
- **Do** design the unhappy paths (empty, error, loading, no-permission, slow-network) for every flow — they are the bulk of real usage.
- **Do** define one primary action per surface; demote everything else visually or structurally.
- **Do** centralize design decisions as tokens/components so changes propagate; never hardcode the same spacing/color in twenty places.
- **Do** meet WCAG 2.2 AA as the default bar: 4.5:1 text contrast, 24px min target spacing, visible focus, no information by color alone. See `.claude/checklists/accessibility.md`.
- **Do** write real interface copy (labels, errors, empty states) — copy is design, not a fill-in-later task.
- **Do** design responsively/adaptively: small + large viewport for GUI, narrow + wide terminal for CLI, varying payloads for APIs.
- **Do-not** start visual polish (color, shadow, animation) before IA and flows are validated.
- **Do-not** introduce a new component when an existing one fits; extend the system instead.
- **Do-not** rely on hover-only or color-only affordances, or ship modals that trap focus or lose keyboard users.
- **Do-not** assume a web app — keep patterns translatable to whatever surface the project actually uses.

## Common mistakes to avoid
- Designing only the success state and discovering error/empty/loading gaps during build.
- "Mystery meat" navigation: unlabeled icons, ambiguous primary actions, hidden destructive actions with no confirmation.
- Inventing personas or requirements not in the spec instead of asking the user one business-critical question.
- Token sprawl: a "spacing system" that has 14 ad-hoc values, or colors copied as hex everywhere.
- Inaccessible defaults: low contrast, tiny tap targets, focus that disappears, forms without labels.
- Over-designing low-traffic surfaces while under-specifying the daily-driver flow.
- Treating CLI/API/agent surfaces as "not UX" — they have the same need for clarity, consistency, and good error messages.

## Output format
A design package (one document or folder) containing: (1) IA tree/sitemap, (2) the top flows with all states enumerated, (3) low-fidelity wireframes/region maps per surface, (4) the design-system baseline (tokens + core components with states), (5) interaction & accessibility rules, (6) real interface copy. Use `.claude/templates/architecture.md` for the system-level structure and link the package from the feature spec (`.claude/templates/product-spec.md`). Keep it diff-friendly (markdown + simple diagrams) so it lives in the repo and stays current.

## Related checklists
- `.claude/checklists/accessibility.md`
- `.claude/checklists/qa.md`
- `.claude/checklists/security.md`

## Related agents
- `.claude/agents/core/orchestrator.md`
- `.claude/agents/design/ui-ux-designer.md`
- `.claude/agents/core/business-analyst.md`