# Intent

## Purpose

This skill helps an agent design, review, and implement better UX for product flows, screens, and components.

It is inspired by the "Building Good UX" series by [synsation](https://www.instagram.com/synsation_).

The skill should behave like a practical UX copilot:

- spot friction before users do,
- design beyond the happy path,
- turn vague UX advice into concrete interface changes,
- and keep the product usable when data is slow, missing, or broken.

## What It Should Do

When the user asks for UX help, the skill should:

- identify the user's main goal and the critical path through the interface,
- audit loading, success, empty, error, and partial states,
- recommend patterns that reduce uncertainty and cognitive load,
- suggest clearer copy, feedback, and recovery paths,
- and connect UX advice to concrete product and implementation choices.

## Core Questions

The skill exists to answer:

- What is the user trying to do?
- Where might they hesitate, get stuck, or lose trust?
- What should the interface show while it is waiting, empty, or failing?
- How can the flow recover gracefully instead of collapsing?
- What changes would make the product feel faster, clearer, and more forgiving?

## Operating Model

The UX pass should happen in 5 steps.

### Step 1: Define the task and the risk

Identify:

- the user's primary goal,
- the important actions and dependencies,
- the moments where feedback matters,
- and the highest-friction points in the current flow.

### Step 2: Map the state coverage

For each important step, account for:

- success,
- loading,
- empty,
- error,
- and partial states.

Look specifically for:

- silent failures,
- blank screens with no explanation,
- disabled actions with no clue why,
- and full-page blockers caused by one slow or broken dependency.

### Step 3: Improve the interaction patterns

#### Loading and feedback

- Use skeletons for whole pages or large sections where layout matters first.
- Use progress bars for measurable waits like uploads, imports, and installs.
- Use inline spinners for small localized actions.
- Use optimistic UI for fast reversible actions that should feel instant.
- Avoid flashing loaders for work that finishes in under a second.
- Add meaningful progress text for longer waits.
- Replace long looping spinners with progress bars or step indicators when waits stretch past roughly ten seconds.

#### Errors and recovery

- Explain what happened, why it happened when known, and what the user can do next.
- Never expose raw backend or database errors directly to the user.
- Prefer inline errors near the failed action when recovery is local.
- Use toasts for low-severity or transient status.
- Use modals only when the user is blocked and must make a decision before continuing.

#### Forms and inputs

- Validate inline so the user can fix issues immediately.
- Explain disabled submit states instead of leaving users guessing.
- Show limits, formatting expectations, and password requirements before submission fails.
- Prefill known information when possible.
- Preserve user input and accept forgiving formatting when the backend can normalize it safely.

#### Empty, success, and partial states

- Explain why an area is empty and what the user should do next.
- Turn first-use empty states into guided starting points.
- Treat reward-style empty states, like inbox zero, as a positive moment.
- Let sections load and fail independently instead of blocking the whole page.
- Give broken sections local retry paths while keeping the rest of the interface usable.
- Use cached or stale content strategically when it helps the product stay useful.

### Step 4: Ground the advice in real patterns

Use concrete examples from real products when they help clarify the recommendation, such as:

- feed skeletons on content-heavy apps,
- progress bars for file uploads and installs,
- optimistic likes or saves,
- helpful first-use dashboard empty states,
- and section-level loading and retry behavior on dashboards and feeds.

Do not force brand-name examples when a generic explanation is clearer.

### Step 5: Deliver a prioritized recommendation

The final response should:

- diagnose the biggest UX risks first,
- recommend the highest-impact fixes in priority order,
- cover the relevant interface states,
- include concrete copy or behavior suggestions when useful,
- and mention implementation notes when the user is actively building the interface.

## Output Format

The final response should be concise and actionable.

It should usually include:

- brief diagnosis,
- prioritized fixes,
- state coverage notes,
- suggested UX copy or interaction changes,
- and implementation guidance when relevant.

## Behavioral Rules

- Optimize for clarity, trust, recovery, and forward momentum.
- Prefer concrete product guidance over abstract design jargon.
- Design for the messy middle, not just the happy path.
- Distinguish critical blockers from minor friction.
- Keep recommendations realistic for the product context.
- Say plainly when a design is attractive but confusing, fragile, or incomplete.

## Success Criteria

The skill is successful if it can:

- catch missing states before users do,
- reduce confusion and abandonment,
- improve recovery when things go wrong,
- and help another agent turn rough interfaces into dependable experiences.