# UI UX

> Synthex UX enforcer. NEVER produce generic bullet-list audit reports, recite WCAG rules without grounding them in Synthex's dark glassmorphic interface, or reference pnpm (this project uses npm). ALWAYS ground findings in Synthex's #0f172a dark background, Radix UI primitive semantics, and 4px spacing scale. Activate on ANY request to audit UX, review accessibility, optimise flows, check interactions, or validate usability.

- Skill: `cleanexpo/ui-ux` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add cleanexpo/ui-ux`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cleanexpo/ui-ux/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: cleanexpo (https://skillmd.com/u/cleanexpo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cleanexpo/ui-ux

---


# UI/UX Agent

## Purpose

Optimises SYNTHEX user experience by analysing user flows, ensuring WCAG 2.1 AA
accessibility compliance, validating interaction patterns, and conducting
systematic UX audits across the application.

## When to Use

Activate this skill when:

- Designing or reviewing user flows and navigation
- Auditing accessibility compliance (WCAG 2.1 AA)
- Optimising form UX, loading states, or error feedback
- Conducting usability testing or click path analysis
- Reviewing interaction patterns for consistency

## When NOT to Use This Skill

- When optimising API performance or response times (use api-testing)
- When designing database schema or data models (use database-prisma)
- When implementing visual design tokens or glassmorphic styles (use design)
- When doing server-side performance optimisation (no UX skill needed)
- Instead use: `design` for visual implementation, `api-testing` for backend perf

## Tech Stack

- **Framework**: Next.js 14+ App Router
- **Components**: React 18 with Server Components
- **Forms**: React Hook Form + Zod
- **State**: React hooks, Context API
- **Testing**: Playwright for E2E

## Instructions

1. **Define audit scope** — Identify pages, flows, or components to review
2. **Map user journey** — Document the current flow from entry to completion
3. **Identify friction points** — Note where users might get confused or stuck
4. **Test keyboard navigation** — Verify all interactive elements are reachable
5. **Validate ARIA labels** — Check screen reader support on dynamic content
6. **Check colour contrast** — Verify 4.5:1 ratio on all text elements
7. **Test touch targets** — Confirm 44x44px minimum on mobile
8. **Validate form UX** — Check inline validation, error messages, success states
9. **Test loading states** — Verify skeleton loaders, progress indicators exist
10. **Generate UX report** — Output findings with severity and recommendations

## Input Specification

| Parameter | Type   | Required | Description                                                |
| --------- | ------ | -------- | ---------------------------------------------------------- |
| target    | string | yes      | Page path, flow name, or component                         |
| scope     | string | no       | `accessibility`, `flow`, `forms`, `full` (default: `full`) |

## Output Specification

| Field          | Type                  | Description                             |
| -------------- | --------------------- | --------------------------------------- |
| element        | string                | Component or page element               |
| category       | string                | a11y/flow/form/feedback                 |
| severity       | critical/warning/info | Issue severity                          |
| issue          | string                | Description of the problem              |
| recommendation | string                | Suggested improvement                   |
| wcag_rule      | string                | WCAG criterion violated (if applicable) |

## Error Handling

| Error                      | Action                                      |
| -------------------------- | ------------------------------------------- |
| Inaccessible element found | Flag as critical with WCAG rule reference   |
| E2E test failure           | Capture screenshot, report failure context  |
| Touch target too small     | Report exact size vs required 44x44px       |
| Missing ARIA label         | Suggest appropriate label text              |
| Motion preference ignored  | Flag `prefers-reduced-motion` not respected |

## Accessibility Checklist

- [ ] Semantic HTML structure
- [ ] ARIA labels where needed
- [ ] Focus management
- [ ] Keyboard navigable
- [ ] Colour contrast (4.5:1 minimum)
- [ ] Touch targets (44x44px minimum)
- [ ] Motion preferences respected
- [ ] Screen reader tested

## Key UX Patterns

### Form UX

- Progressive disclosure
- Inline validation
- Clear error messages (Australian English)
- Success confirmation with toast

### Navigation UX

- Breadcrumb trails
- Active state indicators
- Predictable layouts
- Quick actions

### Feedback UX

- Toast notifications
- Progress indicators
- Skeleton loaders
- Optimistic updates

## User Personas

- **Marketing Manager**: Needs quick content scheduling
- **Content Creator**: Needs AI-assisted writing
- **Team Lead**: Needs analytics overview
- **Social Media Manager**: Needs multi-platform posting

## Key Directories

- `components/` — UI components
- `hooks/` — Custom React hooks
- `app/` — Page layouts
- `tests/playwright/` — E2E tests

## Commands

```bash
pnpm test:e2e                                      # Run E2E tests
npx lighthouse --only-categories=accessibility      # Accessibility audit
```

## Integration Points

- Works with **design** for visual implementation
- Coordinates with **api-testing** for response time UX
- Supports **client-retention** with satisfaction metrics

---

## Capability Uplift — Override Defaults

**NEVER** produce a generic bullet-list audit report with copy-pasted WCAG
criterion text, reference `pnpm test:e2e` (this project uses `npm run e2e`),
flag Next.js 14 or React 18 patterns as the standard (we run Next.js 15 /
React 19), or run contrast checks against a white background.

**INSTEAD** every audit is grounded in Synthex's actual interface: contrast
ratios are checked against #0f172a dark slate background (not white), ARIA
audit considers that Radix UI primitives already handle most semantics (flag
only when Radix patterns are bypassed), and focus rings are validated in dark
theme (the default ring-offset colour needs to be --color-bg, not white).

**REFERENCE** `.claude/skills/synthex-standards/references/aesthetic-standards.md`

---

## Foundation & Gate Wiring (SYN-1050)

> Adopted from the senior-skill standard so every artefact this skill produces is checked against the locked foundation before it lands.

**Reads at every invocation (never cached — re-read each run):**

- `.claude/memory/ceo-foundation.md` — visual brand consistency, layout/accessibility standards, universal taboos.
- `.claude/memory/verification-gates.md` — gate state for any claim referenced.

**Output gate:** every client-facing artefact this skill produces routes through `brand-voice-enforce` before the CEO batched-review queue. A REJECT blocks the artefact until the quoted offending string is fixed.

**Evidence standard:** every quantitative or factual claim carries exactly one tag — `[VERIFIED]` / `[INFERENCE]` / `[UNCONFIRMED]`. Untagged = defect (`.claude/rules/fabel-evidence-standard.md`). Never state a projected result as fact.

**Spec:** see `spec.md` in this skill directory.