/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

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.

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

rg --files
rg "components/ui|shadcn|use client|generateMetadata|useQuery|i18n|design-tokens" .

Then run the project's frontend verification commands, typically lint, typecheck, tests, and browser/responsive checks when the UI changes.

Resource scope

| Scope | Resource target | |-------|-----------------| | `CODEBASE` | Frontend routes, components, styles, hooks, tests | | `LOCAL_FS` | Design tokens, i18n files, resource references | | `PROCESS` | Build, lint, typecheck, test, browser commands | | `NETWORK` | Backend APIs or registry tools when required |

Preconditions

• Target UI behavior and affected frontend area are identifiable.
• Required design tokens, i18n, and API contracts are available or assumptions are stated.

Effects and side effects

• Mutates frontend source, styles, tests, and possibly i18n keys.
• May add dependencies or shadcn components only when justified by project conventions.
• Does not edit `components/ui/*` directly.

Guardrails

Apply framework, library, architecture, and data-model defaults only when the target project has no established