Ui Software Engineer

UI Software Engineer

When to Use

• Implement screens and components from Figma or design specs
• Apply design tokens (color, type, spacing) and design-system primitives
• Build states: default, hover, focus, disabled, loading, empty, error
• Wire read-only or form UI to existing APIs (loading, success, validation display)
• Fix layout and responsive breakpoints per spec
• Add basic accessibility: labels, focus order, keyboard activation
• Create Storybook (or equivalent) stories for components
• Run visual QA against design before PR

When NOT to Use

• Front-end architecture, RSC strategy, bundle/CWV optimization → senior-frontend-software-engineer
• Login, cookies, CSRF, CORS, CSP → web-application-developer
• Wireframes, user research, design critique only → product-designer
• Flow specs, heuristic audits, prototypes before visual build → ux-software-engineer
• New REST API, database, or full vertical feature → fullstack-software-engineer
• Deploy pipelines → devops

Related skills

Core Workflows

1. Design handoff to code

Spec checklist, tokens, assets, unknowns.

See `references/design_handoff.md`.

2. Components and states

Presentational vs container, variants, composition.

See `references/components_and_states.md`.

3. Layout and tokens

Grid, spacing, typography, responsive rules.

See `references/layout_tokens.md`.

4. API boundary in UI

Fetch hooks, skeletons, errors, empty states.

See `references/ui_data_states.md`.

5. Accessibility basics

Labels, contrast, keyboard, focus visible.

See `references/ui_a11y_basics.md`.

6. Stories and visual QA

Storybook, screenshot compare, PR checklist.

See `references/stories_visual_qa.md`.

Output standards

• Match design tokens — no magic hex outside token map
• Every interactive control has visible focus and accessible name
• Loading / empty / error implemented for async views
• PR includes screenshots or Storybook link for changed UI
• Escalate spec gaps to product-designer before guessing layout

When to load references

• Handoff → references/design_handoff.md
• Components → references/components_and_states.md
• Layout → references/layout_tokens.md
• Data UI → references/ui_data_states.md
• A11y → references/ui_a11y_basics.md
• QA → references/stories_visual_qa.md

Components and States

Presentational vs container

Keep presentational components in Storybook without API mocks when possible.

Variants

Use design-system API (variant, size) — do not fork CSS per screen.

<Button variant="primary" size="md" disabled={isSubmitting} />

State matrix (minimum per interactive surface)

Composition

• Prefer small composable pieces over 500-line page files
• Extract when used twice or spec defines reusable pattern
• Page = layout + sections; section = heading + content slot

When to escalate

• New primitive not in design system → senior-frontend-software-engineer + design
• Cross-route state architecture → senior FE, not one-off context soup

Design Handoff

Pre-build checklist

• [ ] Figma link + version pinned (or export date)
• [ ] Tokens documented (color, font, radius, shadow)
• [ ] Breakpoints listed (mobile, tablet, desktop)
• [ ] All states shown: hover, focus, disabled, error
• [ ] Copy final or flagged TBD
• [ ] Icons/assets export path (SVG preferred)
• [ ] Edge cases: long text, empty, max items

Questions to resolve before coding

Route UX gaps to product-designer; do not invent major flows.

Implementation order

1. Static layout + tokens (no data) 2. States with mock data 3. API wiring + loading/error/empty 4. A11y pass + keyboard 5. Visual QA vs Figma

Anti-patterns

• Screenshot-to-code without token mapping
• Hardcoded pixels from inspect tool only
• Shipping without error/empty for lists and forms

Layout and Tokens

Token usage

If token missing, add to design system — do not local-patch unless emergency.

Responsive

Match Figma frames to breakpoints explicitly in PR notes.

Layout patterns

• Stack: vertical rhythm with consistent gap token
• Grid: columns defined at breakpoint; avoid fixed px widths
• Sticky header/footer: test with keyboard scroll and zoom 200%

Content stress

• Long titles: truncate + title tooltip if spec allows
• RTL/i18n: avoid hardcoded ml-; use logical properties (ms-, me-) when project supports

Visual polish (IC scope)

• Align to 4px or 8px grid per system
• Icon size paired with text line-height
• Deep CWV work → senior-frontend-software-engineer

Stories and Visual QA

Storybook (or equivalent)

Each reusable component:

Name stories to match design spec terms.

PR checklist

• [ ] Storybook updated for changed components
• [ ] Screenshots: before/after for visual change
• [ ] Responsive: mobile + desktop capture
• [ ] States: error/empty if applicable
• [ ] No console errors in story and page
• [ ] Token compliance (no stray hex)

Visual compare

Log known deltas (font rendering, browser) in PR description.

Regression

• Do not change shared component without checking consumers
• Run smoke on critical flows if touching layout shell

Scope boundary

• E2E test authoring → QA or fullstack preference
• Unit test logic → team standard; UI engineer adds interaction tests when required

UI Accessibility Basics

Minimum bar (every PR)

• [ ] Interactive elements are native or roled correctly (button, link, input)
• [ ] Every input has visible label (<label> or aria-label if icon-only)
• [ ] Focus order follows visual order
• [ ] Focus visible on keyboard tab
• [ ] Color contrast meets WCAG AA for text and controls (use token pairs)
• [ ] Images/icons have alt or aria-hidden if decorative
• [ ] Modals trap focus and restore on close

Keyboard

Do not

• div onClick without role and keyboard handler
• outline: none without replacement focus style
• Placeholder as sole label
• Disable zoom (user-scalable=no)

When to involve senior FE

• Complex widgets (combobox, datagrid)
• Full page audit or WCAG sign-off
• See senior-frontend-software-engineer → references/a11y_performance.md

Quick tests

1. Tab through feature without mouse 2. 200% browser zoom — no clipped controls 3. Screen reader spot-check on primary flow (optional but valuable)

UI Data States

Boundary responsibility

UI engineer consumes existing API; does not design schema.

Async UI pattern

idle → loading → success | error | empty

Forms

• Disable submit while pending
• Show field errors from API validation map
• Preserve user input on recoverable error
• Success: toast or redirect per spec

Lists and tables

• Pagination or infinite scroll per spec
• Row actions disabled while mutation in flight
• Optimistic UI only if fullstack documents rollback behavior

Escalation

• New endpoint or contract change → fullstack-software-engineer
• Auth redirect / 401 handling in app shell → web-application-developer