Frontend UX Standards

Owner: Frontend Engineering Last reviewed: 2026-Q2

This page defines UI and UX expectations for WorkOpti frontend changes.

Product Fit

• WorkOpti is an operational productivity tool. Interfaces should be quiet, dense enough for repeated use, and easy to scan.
• Prefer clear workflows over decorative layouts.
• Build the actual working screen first; avoid marketing-style shells for application features.

Components

• Prefer existing src/components/ui/* primitives and feature components before creating new UI.
• Use Radix/shadcn-style components for dialogs, sheets, menus, selects, popovers, alerts, tooltips, and forms.
• Use lucide icons for common icon actions when available.
• Keep reusable components accessible by default: labels, focus states, keyboard behavior, and ARIA where needed.

States

Every user-facing workflow should handle:

• Loading state.
• Empty state.
• Error state with user-readable copy.
• Permission-denied/read-only state where relevant.
• Success feedback for non-obvious mutations.
• Disabled/pending state for in-flight actions.

Layout

• Design mobile and desktop behavior intentionally.
• Avoid fixed widths that break at mobile sizes.
• Keep toolbar, board, modal, and form controls stable so loading text or long labels do not shift the layout unexpectedly.
• Do not nest cards inside cards; use cards for repeated items, dialogs, and framed tools.

Forms

• Use react-hook-form and zod where validation complexity justifies it.
• Validate before submit and surface field-level messages when possible.
• Preserve user input on recoverable errors.
• Disable duplicate submits while a mutation is in flight.

Data And Permissions

• Use generated API clients through thin wrappers in src/api/*.
• Keep TanStack Query keys and invalidation explicit.
• Render read-only UI for viewer-level access rather than hiding all context.
• Do not trust frontend permission checks as security boundaries; backend authorization remains authoritative.

Accessibility And QA

• Verify keyboard access for dialogs, menus, popovers, and destructive actions.
• Ensure focus returns to a sensible element after modal close.
• Check color contrast for text, badges, and disabled states.
• Test important flows at mobile and desktop breakpoints.
• Run npm run lint and npm run build before review.