UX Best Practices

This skill covers UX patterns for creating exceptional user experiences — visual hierarchy, error handling, loading states, and empty states.

Use-When

This skill activates when:

• Agent designs page layouts
• Agent builds forms with validation
• Agent creates async operations with loading states
• Agent displays lists that might be empty
• Agent handles API errors

Core Rules

• ALWAYS use consistent spacing from the design system
• ALWAYS show loading states during async operations
• ALWAYS provide clear, specific error messages
• ALWAYS provide empty states for lists/collections
• ALWAYS allow error recovery when possible

Common Agent Mistakes

• Inconsistent spacing throughout the layout
• Generic error messages like “An error occurred”
• Not disabling buttons during form submission
• Showing empty tables without helpful messaging

Examples

✅ Correct

// Consistent spacing
<div className="space-y-4">
  <h1 className="text-2xl font-bold">Title</h1>
  <p>Content</p>
  <Button disabled={isLoading}>
    {isLoading ? "Loading..." : "Submit"}
  </Button>
</div>

// Specific error message
catch {
  toast.error("Failed to save. Please try again.")
}

❌ Wrong

// Random spacing
<div className="p-2">
  <h1 className="mb-3">Title</h1>
  <p className="mb-6">Content</p>
</div>

// Generic error
catch {
  toast.error("An error occurred")
}

References

• Visual Hierarchy – Nielsen Norman Group
• Error Message Guidelines – Nielsen Norman Group