/build-for-good-ux-skill

name: build-for-good-ux
description: Use when building, reviewing, or improving user-facing UI, frontend components, pages, forms, flows, loading states, error handling, empty states, success feedback, graceful degradation, familiar layouts, or choice-heavy interfaces.

Build For Good UX

Based on Katherine Gilligan's public "Build For Good UX" series ([@synsation_](https://instagram.com/synsation_)). Use this as an implementation checklist for UI work, not as transcript notes.

Core Principle

Good UI is how an app looks. Good UX is whether users understand what to do, what happened, what failed, and how to recover. AI-generated UI often covers only the happy path. Build the full experience.

Every screen needs these states:

| State | Required UX | |---|---| | Loading | Shows progress appropriate to wait time and scope | | Success | Confirms the user's action worked | | Error | Explains what happened, why, and next action | | Empty | Explains why nothing is there and how to start or continue |

Good UX builds trust. Bad UX creates uncertainty, extra steps, and friction. Users leave and blame the product, not themselves.

Required Workflow

When building or reviewing a UI, do this before considering the work complete:

1. Identify every user action and async data source. 2. Define loading, success, error, and empty states for each relevant screen or section. 3. Pick the loader based on scope and duration. 4. Place errors next to the thing that caused them unless the issue blocks the whole flow. 5. Ensure every action gives visible feedback. 6. Make each page section resilient when other sections load slowly or fail. 7. Use familiar patterns for the user's device, locale, and audience. 8. Reduce choice overload with grouping, curation, filtering, or progressive disclosure. 9. Verify the final checklist at the bottom of this file.

Loading States

Missing loaders make users think the app is broken. A blank screen with no response can lose users in 2-3 seconds. Bad loaders can also make the app feel slower.

Choose Loader By Context

| Pattern | Use When | Avoid When | |---|---|---| | Skeleton screen | Whole page or large content section loads | Small contained action | | Progress bar | Duration or progress is knowable | Unknown background wait | | Inline spinner | Button or small section is working | Whole page load | | Optimistic UI | Action is very likely to succeed | Failure would be costly or confusing | | No loader | Work finishes under 1 second | Delay may exceed 1 second |

Timing Rules

| Duration | UX Rule | |---|---| | Under 1 second | Show result, no loader. Spinner flash feels slower. | | 1-2 seconds | Plain spinner is enough. | | 2-5 seconds | Spinner still works. | | 5-10 seconds | Add text. Prefer changing text like "Connecting..." then "Almost there...". | | Over 10 seconds | Replace looped spinner with progress bar or step indicator. | | On failure | Show error as soon as possible. Do not make users wait then fail. |

Skeleton Rules

• Show page structure first as gray placeholder outlines.
• Match final layout closely so users start processing structure before data arrives.
• Use skeletons for feeds, dashboards, profiles, and content-heavy pages.
• Use inline spinners for buttons or small parts where skeletons do not fit.

Optimistic UI Rules

• Update UI immediately when action is likely to succeed, like a like/favorite/toggle.
• Do not wait for server confirmation before showing the expected result.
• If the server fails, roll back clearly and gracefully.
• Do not use optimistic UI for payments, destructive actions, bookings, or anything where false success creates risk.

Error States

Errors must reduce uncertainty. Never leave users wondering whether an action worked.

Error Message Formula

Good error messages include all three:

1. What happened. 2. Why it happened, in user language. 3. What the user can do next.

Bad:

Something went wrong.

Good:

Your payment didn't go through. Your card was declined. Check your card details or try a different payment method.

Error Rules

• Never dump database, backend, stack trace, or raw exception details into UI.
• Never silently fail. A clicked button must produce feedback.
• Avoid vague messages when user needs certainty.
• Always provide recovery: retry, edit, request access, update payment, or contact support.
• Show errors immediately when known. Do not hide failure behind long loading.

Error Placement

| Placement | Use When | Rules | |---|---|---| | Inline | Field-specific errors, button action failure, most forms | Closest to the problem. Use red border plus message. | | Toast | Non-critical, recoverable status | Auto-dismiss only if user can miss it without harm. Example: "Couldn't connect, retrying..." | | Modal | Critical blocker requiring user action | Blocks flow. Must include clear next action. Use sparingly. |

If blocking the user with a modal, provide a way forward.

Form UX

Forms create friction. Reduce effort, uncertainty, and rework.

Form Rules

1. Disable submit until required fields are valid, but explain what is missing. 2. Mark required fields clearly so users are never guessing why submit is disabled. 3. Validate inline when users leave a field, not only after submit. 4. Keep validation messages near the field, not at the top of the page. 5. Show character counts for limited fields. 6. Pre-fill known values, such as logged-in user's email. 7. Show password requirements while typing and check them off live. 8. Accept forgiving formats, such as phone numbers with spaces, dashes, parentheses, or no formatting. Normalize in code. 9. For forms with more than seven fields, consider splitting into multiple steps or sections.

Form Mistakes To Avoid

• Disabled button with no explanation.
• Submit, wait, then scroll to find errors.
• Rejecting user input because formatting differs from preferred display format.
• Making u