agentleFS
naman10parikhnaman10parikh/pixel/.claude/skills/ux-audit/SKILL.md

ux-audit

Skill0 starsChanged 28 days agoMITView on GitHub

Systematic UX audit for Spark and Energy platform. Checks component consistency, accessibility, duplicate elements, responsive layout, and interaction patterns. Run before any demo or commit.

28 other projects use a version of this, 2 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 23 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    After building or modifying any UI component

    line 8
  2. Distinctive:

    Before presenting work to Naman

    line 9
  3. Distinctive:

    When onboarding a new page to the platform

    line 11

“Common” is measured: kept by at least 6 in 10 of the 23 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

When to Use

  • After building or modifying any UI component
  • Before presenting work to Naman
  • As part of /wrap-up session protocol
  • When onboarding a new page to the platform

UX Audit Checklist

1. Component Consistency

  • No duplicate elements (avatars, indicators, icons showing twice)
  • Consistent spacing (px-4/px-6 pattern, not mixed)
  • Same border radius pattern (rounded-xl for cards, rounded-2xl for containers)
  • Color tokens used everywhere (no hardcoded hex outside globals.css)
  • All interactive elements have hover states with hover-lift or color change

2. Layout & Responsiveness

  • Mobile-first: every page works on 375px width
  • No horizontal scroll on any breakpoint
  • Navigation accessible on mobile (hamburger or stack)
  • Text readable without zoom (min 14px body, 11px smallest)
  • Cards stack on mobile, grid on desktop

3. Loading & Streaming States

  • Every async action shows loading state
  • Streaming text has cursor indicator
  • No flash of unstyled content (FOUC)
  • Skeleton or shimmer for data-dependent areas
  • Error states are user-friendly (not raw error messages)

4. Accessibility Basics

  • All buttons have accessible names (text or aria-label)
  • Links with icons have title attributes
  • Color contrast meets WCAG AA (4.5:1 for text)
  • Focus indicators visible on keyboard navigation
  • Form inputs have labels or placeholders

5. Brand Consistency

  • Warm black background (#141312), not pure black
  • Instrument Serif for display text (font-display class)
  • Poppins for body (font-sans)
  • Rose-500/600 for Spark accent, purple for Energy platform
  • Bento-style asymmetric grids (not uniform)

6. Interaction Patterns

  • Enter key submits forms
  • Escape key closes modals/menus
  • Back navigation works (no dead ends)
  • Empty states guide user to action
  • Success feedback on mutations (save, delete, send)

How to Execute

Method A: Code Review (No Browser)

1. Grep for common UX antipatterns:
   - Duplicate components in same view
   - Missing loading states (isLoading without UI)
   - Hardcoded colors outside theme
   - Missing error boundaries
   - Non-responsive layouts (fixed widths)

2. Check component tree:
   - Each page has proper hierarchy
   - Shared components extracted (not copy-pasted)
   - State doesn't leak between routes

3. Review all pages systematically:
   /spark → landing
   /spark/chat → chat interface
   /spark/pricing → pricing
   /spark/history → date history
   /spark/settings → preferences

Method B: Browser Testing (Preferred)

1. Start dev server: pnpm --filter @energy/web dev
2. Use Chrome extension or --chrome flag
3. Navigate each page in sequence
4. Check mobile view (375px) and desktop (1440px)
5. Test all interactive flows:
   - Onboarding → Chat → Save Plan → View History
   - Settings → Save → Return to Chat
   - Pricing → Checkout flow
6. Screenshot and report issues

Method C: Automated Checks

# TypeScript compilation (catches missing props, wrong types)
pnpm --filter @energy/web exec tsc --noEmit

# Build check (catches import errors, SSR issues)
pnpm --filter @energy/web build

# Lint (catches code quality issues)
pnpm --filter @energy/web exec next lint

Common UX Bugs to Watch For

BugCauseFix
Duplicate avatar/iconTwo components both rendering same elementRemove redundant one
Flash of wrong contentClient-side check without hasChecked guardAdd loading gate
Scroll jump on new messageMissing smooth scroll or wrong refuseEffect with scrollIntoView
Input loses focusComponent re-render replacing inputUse controlled component with ref
Mobile nav overflowToo many items in rowCollapse to hamburger or hide
Stale data after actionMissing state refresh after mutationRe-fetch or update local state

Output Format

## UX Audit — [Page Name] — [Date]

### Issues Found

1. **[SEVERITY]** Description — File:line — Fix

### Passed Checks

- [x] Component consistency
- [x] Loading states
      ...

### Recommendations

- Consider adding...

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.