Ux Software Engineer

UX Software Engineer

When to Use

• Turn user journeys into flow diagrams and interaction specs
• Build clickable or coded prototypes to validate flows before production
• Run heuristic UX audits on existing product and prioritize fixes
• Define interaction details: validation timing, focus, undo, confirmations
• Improve IA: navigation, labeling, grouping, empty paths
• Write UX acceptance criteria for ui-software-engineer or fullstack
• Partner on usability tests (tasks, success metrics, synthesis to tickets)
• Refine microcopy in UI (labels, errors, empty states) with product voice

When NOT to Use

• Greenfield discovery, wireframes without build intent → product-designer
• Final visual implementation and token-perfect screens → ui-software-engineer
• Core Web Vitals, bundle, RSC architecture → senior-frontend-software-engineer
• Formal requirements and process maps → business-analyst
• Marketing site copy → tech-writer-researcher

Related skills

Core Workflows

1. Flows and interaction specs

Journey → screens → transitions → states.

See `references/flows_interaction_specs.md`.

2. Prototypes in code

When to prototype; fidelity levels; validation loops.

See `references/prototypes_in_code.md`.

3. Heuristic evaluation

Nielsen-style pass; severity; fix tickets.

See `references/heuristic_evaluation.md`.

4. Information architecture

Nav, taxonomy, findability in product.

See `references/information_architecture.md`.

5. UX handoff to engineering

Acceptance criteria, edge cases, open questions.

See `references/ux_engineering_handoff.md`.

6. Microcopy and content UX

Labels, errors, empty states, tone.

See `references/microcopy_content_ux.md`.

Output standards

• Every flow documents entry, success, error, and exit
• Prototypes link to test tasks and assumptions
• Audit findings ranked severity + effort
• Handoff lists interaction rules, not only screenshots
• Escalate visual brand decisions to product-designer

When to load references

• Flows → references/flows_interaction_specs.md
• Prototypes → references/prototypes_in_code.md
• Heuristics → references/heuristic_evaluation.md
• IA → references/information_architecture.md
• Handoff → references/ux_engineering_handoff.md
• Copy → references/microcopy_content_ux.md

Flows and Interaction Specs

Flow diagram minimum

For each journey:

Use Mermaid flowchart or numbered steps—pick one per doc and stay consistent.

Interaction spec per screen

### Screen: Checkout — Payment

**Purpose:** Collect payment without losing cart context.

**Primary action:** Pay now (enabled when card valid + terms checked).

**States:** loading | empty cart redirect | validation error | processing | success | payment declined

**Validation:** Inline on blur for card fields; block submit until terms accepted.

**Focus:** First invalid field on submit failure; trap focus in modal if used.

**Undo:** Back returns to shipping; confirm if payment partially entered.

**Analytics:** checkout_payment_viewed, payment_submitted, payment_failed (reason code)

Transition rules

Edge cases checklist

• Session timeout mid-flow
• Double submit
• Back button after partial save
• Permission change mid-flow
• Concurrent edit (another tab)
• Offline / slow network
• Empty search results
• Rate limit / quota exceeded

Acceptance criteria template

Given [context]
When [user action]
Then [system response]
And [focus/announcement if a11y-relevant]

Pair with product-designer

• Wireframes or Figma frames are inputs—not substitutes for interaction rules
• Open UX questions flagged before ui-software-engineer builds production UI

Heuristic Evaluation

When to run

• Before major release on changed flows
• After support tickets cluster on confusion
• When metrics drop (activation, completion) without clear technical cause
• Complement—not replace—usability testing with real users

Nielsen heuristics (quick pass)

Severity scale

Finding format

**[S2] Checkout — Error recovery**
Heuristic: 9
Issue: Card decline shows only "Error" with no retry path.
Impact: Users abandon; support volume.
Recommendation: Show decline reason (safe subset), keep form data, primary "Try again".
Effort: S
Owner: ui-software-engineer

Scope the audit

• One primary persona per pass
• One journey at a time (e.g. onboarding day 1)
• Desktop and mobile if both supported
• Keyboard-only pass for critical flows (coordinate with senior-frontend-software-engineer for WCAG depth)

Output

1. Executive summary (top 5 fixes) 2. Full table sorted by severity 3. Linked tickets with acceptance criteria 4. "Won't fix" with rationale

Avoid

• Opinion without task context ("I don't like blue")
• Replacing product strategy debates—escalate to PM/design
• Claiming WCAG compliance from heuristics alone

Information Architecture in Product

IA deliverables in engineering context

Navigation patterns

Findability checklist

• Can user reach any primary task in ≤3 clicks from home?
• Search covers the objects users name in support tickets?
• Filters match how users describe segments (not only DB fields)?
• Breadcrumbs reflect hierarchy, not history stack only?
• Settings vs product features clearly separated?

URL and routing UX

• Human-readable slugs where shareable
• Stable URLs for bookmarked admin views
• Redirect old paths after IA change
• 404 with recovery paths (search, home, support)

Empty and overflow states

IA change process

1. Inventory current routes and analytics top paths 2. Card sort or tree test if labels contested (product-designer may lead) 3. Map old → new URLs and comms for breaking changes 4. Ship with analytics on nav clicks and search queries 5. Review 2 weeks post-launch

Handoff to engineering

Provide:

• Nav component spec (items, icons, badges, roles)
• Route table with auth requirements
• Redirect map
• Analytics event names for nav interactions

Microcopy and Content UX

Scope

In-product strings UX engineers own or review:

• Buttons and links
• Form labels and hints
• Validation and API errors
• Empty states
• Toasts and banners
• Confirm dialogs
• Onboarding steps

Public marketing and legal copy → tech-writer-researcher / legal.

Principles

Error message formula

[What happened] + [Why if helpful] + [Next step]

Examples:

• Bad: Error 422
• Good: That email is already registered. Sign in or reset your password.

Empty states

Include:

1. Why it's empty (first use vs filtered out) 2. Primary action to fix 3. Secondary learn-more if complex

Confirm dialogs

Title = consequence; body = what cannot be undone.

Tone matrix (adjust per brand)

Review checklist

• [ ] Jargon and acronyms defined or removed
• [ ] Title case consistent per design system
• [ ] Punctuation consistent (periods in sentences, not in labels)
• [ ] Numbers and units localized if product is i18n
• [ ] Screen reader: errors associated with fields (aria-describedby)

Handoff

• Copy in table: key | en | context | max length
• Flag strings that need truncation rules in UI
• Pair with ui-software-engineer for overflow in components

Prototypes in Code

When to prototype in code vs design tool

Fidelity levels

Do not hi-fi prototype what lo-fi can disprove.

Stack choices (match the product)

• Reuse design system components when possible—prototypes should feel like shipping UI
• Mock API with fixtures; document which fields are fake
• Route behind feature flag or /prototype/* path; never ship prototype routes to prod without guard

Validation loop

1. Write 3–5 task scenarios (no hints in UI copy) 2. Run with 3–5 users or internal proxies; record time and errors 3. Log severity: blocker / major / minor / cosmetic 4. Decide: iterate prototype, change spec, or escalate to product-designer

Prototype hygiene

• Label prototype UI (“Preview”) if shown outside eng
• No real PII in fixtures
• Delete or gate dead prototype code after decision
• Link prototype PR to UX spec doc or ticket

Handoff from prototype

UX Engineering Handoff

Handoff chain

product-designer (discovery, wireframes)
        ↓
ux-software-engineer (flows, interaction, prototype validation)
        ↓
ui-software-engineer (visual production, tokens, component polish)
        ↓
senior-frontend-software-engineer (perf, a11y depth, arch) when needed

Minimum handoff package

State matrix template

What ui-software-engineer needs from you

• Behavior frozen; visual can follow design system
• Component variants named (e.g. destructive, compact)
• Spacing intent if not in system (e.g. "dense table")
• Do not assign hex values if tokens exist—reference token names

What you need from ui-software-engineer

• Storybook links for built states
• Gaps filed when design system cannot express spec

Review gates

Ticket splitting

Anti-patterns

• Screenshot-only tickets without expected behavior
• "Make it like [competitor]" without task context
• Mixing UX spec changes into unrelated refactors