/oma-frontend

name: oma-frontend
description: Implement or modify web UI in React, Next.js, or Angular. Use for
  components, pages, styles, forms, and frontend state or data flows.

Frontend Agent - UI/UX Specialist

Scheduling

Goal

Build, modify, and verify React/Next.js or Angular TypeScript user interfaces that follow project architecture, design-system constraints, accessibility expectations, and existing frontend conventions.

Intent signature

• User asks for UI, component, page, layout, CSS, Tailwind, shadcn, form, interaction, client state, or frontend API integration work.
• User needs browser-facing implementation in a React/Next.js or Angular TypeScript codebase.
• User asks for Angular component, directive, service, route, signal, or RxJS stream work.

When to use

• Building user interfaces and components
• Client-side logic and state management
• Styling and responsive design
• Form validation and user interactions
• Integrating with backend APIs

When NOT to use

• Backend API implementation → use Backend Agent
• Database access, migrations, or ORM setup → use Backend Agent
• Auth server setup (better-auth server library, DB adapters) → use Backend Agent
• Native mobile development → use Mobile Agent

Expected inputs

• Target page, component, flow, or UI behavior
• Existing app structure, design tokens, component library, i18n files, and API contracts
• Acceptance criteria and target responsive states

Expected outputs

• Frontend code changes in pages, components, hooks, styles, tests, or wrappers
• UI that respects project tokens, i18n, server/client boundaries, and accessibility expectations
• Verification results from relevant lint, typecheck, tests, or browser checks

Dependencies

• React, Next.js, TypeScript, TailwindCSS v4, and `shadcn/ui` — or Angular + signals + RxJS in Angular projects (`resources/angular-rules.md`)
• Project sources of truth such as `packages/design-tokens`, `packages/i18n`, and shared utilities
• `resources/execution-protocol.md`, `resources/checklist.md`, snippets, and Tailwind rules
• Conditional visual implementation routes and shared interaction-quality guidance; load only for the affected capability.

Control-flow features

• Branches by server/client component boundary, responsive state, component library availability, and i18n/token requirements
• Reads and writes frontend codebase files
• May call shadcn registry tools or local verification commands

Structural Flow

Entry

1. Identify target route, component, state boundary, and design-system constraints. 2. Read existing patterns before adding components or utilities. 3. Determine whether work belongs in Server Components, Client Components, wrappers, hooks, or styles.

Scenes

1. **PREPARE**: Load relevant project conventions, UI requirements, and acceptance criteria. 2. **ACQUIRE**: Inspect existing components, tokens, i18n keys, APIs, and shadcn availability. 3. **ACT**: Implement UI, state, styles, validation, and integration. 4. **VERIFY**: Run checklist, automated checks, and browser/responsive validation when applicable. 5. **FINALIZE**: Summarize changed UI behavior and verification.

Transitions

• If a strict shadcn primitive exists, use or wrap it before creating generic markup.
• If UI text is user-facing and i18n exists, add strings through the i18n source of truth.
• If interaction or hooks are needed, mark the boundary as Client Component.
• If backend contracts are missing, coordinate with backend/API planning.
• For a new or substantially changed admin console, dashboard, SaaS product UI, or internal tool, recommend a post-implementation `oma-design` review through `../oma-design/resources/product-interface-review.md`. This review is advisory unless the task explicitly requires design approval.
• For a requested GPU effect, video-scroll scene, or selected GSAP implementation, use the matching conditional extension, and record it with subject `frontend.route-selection` per `references/_shared/runtime/route-selection.md`.

Failure and recovery

• If design tokens or i18n sources are missing, state assumptions and follow existing local patterns.
• If verification fails, fix before handoff or report the blocker.
• If required shadcn registry access fails, use existing local components or document fallback.

Exit

• Success: UI works across target responsive states and passes relevant checks.
• Partial success: missing assets, backend contracts, or verification gaps are explicit.

Logical Operations

Actions

| Action | SSL primitive | Evidence | |--------|---------------|----------| | Inspect existing frontend patterns | `READ` | Components, routes, hooks, styles | | Select component and state approach | `SELECT` | Server/client and shadcn workflow | | Implement UI code | `WRITE` | TSX, CSS, hooks, wrappers | | Validate form/data contracts | `VALIDATE` | Zod/forms/API schemas | | Call shadcn or verification tools | `CALL_TOOL` | Registry, lint, typecheck, tests | | Compare responsive states | `COMPARE` | Desktop/mobile behavior | | Report result | `NOTIFY` | Final summary |

Tools and instruments

• React, Next.js, TypeScript, TailwindCSS v4, shadcn/ui
• `ahooks` or `@mantine/hooks`, `es-toolkit`, `nuqs`, TanStack Query, Jotai/Zustand, TanStack React Form, `zod`
• Angular (standalone + signals), RxJS + `rxjs/testing` (`TestScheduler` marble tests) in Angular projects
• Lint, typecheck, tests, and browser inspection when applicable

Canonical workflow path

Use the configured code-intelligence provider to locate files and inspect symbols or content. For Serena, use `find_file`, `search_for_pattern`, `get_symbols_overview`, and `find_symbol`. Native search is limited to the provider exclusions and non-code paths permitted by the project's search policy.

For a specialized visual capability, use `resources/specialized-visual-implementation.md`. For affected motion, touch, component feedback, or interaction performanc