Initial commit

openclaw/building-good-ux/README.md

@@ -0,0 +1,14 @@
+# OpenClaw Package
+
+This folder contains the OpenClaw version of `building-good-ux`.
+
+## Packaging notes
+
+- The package mirrors the shared skill behavior from the repo root.
+- `SKILL.md` is the installable artifact copied into the target skills directory.
+- Keeping the wording aligned with the other harness folders makes cross-ecosystem maintenance simpler.
+
+## Source
+
+- `Intent.md` in the repo root
+- shared repository packaging conventions

openclaw/building-good-ux/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: building-good-ux
+description: Improve product and interface UX by reviewing or designing flows, screens, components, forms, and async states. Use when Codex needs to critique, redesign, or implement better loading, empty, error, partial, or success states, reduce form friction, choose feedback patterns, or make AI-generated UI less happy-path-only and more trustworthy.
+---
+
+# 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.