Oma Frontend

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

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

Scenes

• PREPARE: Load relevant project conventions, UI requirements, and acceptance criteria.
• ACQUIRE: Inspect existing components, tokens, i18n keys, APIs, and shadcn availability.
• ACT: Implement UI, state, styles, validation, and integration.
• VERIFY: Run checklist, automated checks, and browser/responsive validation when applicable.
• 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

• Follow the existing React, Next.js, TypeScript, and FSD-lite architecture in the target project.
• Use shadcn/ui primitives and wrappers for UI work; treat components/ui/* as read-only.
• Keep server/client boundaries explicit: Server Components for static/layout work, Client Components for interaction and hooks.
• Use project sources of truth for design tokens, i18n strings, and shared utilities before adding local alternatives.
• Run the execution checklist before handoff and include relevant verification results.
• Self-describing file names: every new file follows the File Naming convention in ../../rules/frontend.md §Naming Conventions — domain + role readable from the basename alone (order-summary-card.tsx, use-order-polling.ts, cart.atoms.ts). Grab-bag names (utils.ts, helpers.ts, misc.ts) and version suffixes (*-v2, *-final) are banned.
• Next.js 16 proxy.ts is mandatory; middleware.ts is BANNED: this project is Next.js 16+. middleware.ts is NOT "deprecated"; it is forbidden, touch it and you die. The canonical request-proxy / auth-gate file is proxy.ts (root or src/) exporting a proxy function. NEVER create, recommend, suggest, or "restore" middleware.ts. NEVER flag proxy.ts as dead code, unused, or not-wired. Any such finding is a fatal self-error: retract it immediately and write proxy.ts.
• next/link defaults to prefetch={false}: every <Link> MUST pass prefetch={false} unless there is a stated reason not to. Next.js's default prefetching fires a request per link entering the viewport, which hammers container CPU/memory and origin bandwidth on list-heavy or nav-heavy pages. Opt back in (prefetch omitted, or prefetch / prefetch="unstable_forceStale") ONLY for a small, deliberate set of high-intent targets (primary CTA, next step in a funnel), and note the reason inline. A <Link> without an explicit prefetch decision fails review.
• Angular projects follow resources/angular-rules.md: standalone components + OnPush + signals-first, inject() DI, lazy routes, new control flow. Any non-trivial RxJS pipeline MUST ship with a marble test (TestScheduler from rxjs/testing) — a stream without a marble test fails review. React/Next.js-specific rules (shadcn workflow, proxy.ts, Libraries table below) do not apply in Angular projects.

Libraries

React/Next.js projects only — Angular projects use the Angular-native equivalents in resources/angular-rules.md (signals, typed Reactive Forms, HttpClient/httpResource, RxJS with mandatory marble tests).

| Category | Library |

|----------|---------|

| Framework | next@16+ (App Router) + react@19+; next < 16 is BANNED |

| Date | luxon |

| Styling | TailwindCSS v4 + shadcn/ui (Base UI engine; see resources/tech-stack.md) |

| Hooks | ahooks (default) or @mantine/hooks (standalone, SSR-safe; no Mantine UI required); pre-made hooks preferred; pick one per project, don't mix |

| Utils | es-toolkit (first choice) |

| Types | type-fest (TS type utilities not in the standard lib: SetRequired, Merge, JsonValue, Promisable, etc.; built-in Partial/Pick/Omit stay first choice) |

| State (URL) | nuqs |

| State (Server) | TanStack Query; default is orval-generated hooks from the OpenAPI spec (client: react-query); hand-write hooks only for spec-less endpoints (see resources/tech-stack.md §Server State) |

| State (Client) | Jotai or Zustand (intent-based, no default; minimize use — see resources/tech-stack.md) |

| Forms | @tanstack/react-form (v1+; pass zod schemas directly via Standard Schema; @tanstack/zod-form-adapter is v0-only and BANNED) + zod (v4) |

| Auth | better-auth (client SDK only; never import server library or database adapters) |

| Animation | motion; import from motion/react. framer-motion (legacy package name) is BANNED. |

Shadcn Workflow

• Engine default: Base UI (components.json → style: "base-*"). Radix (radix-*) is a

reasoned fallback for existing Radix codebases only; no big-bang migration. Details in

resources/tech-stack.md §shadcn/ui Primitive Engine.

• Search: shadcn_search_items_in_registries
• Review: shadcn_get_item_examples_from_registries
• Install: shadcn_get_add_command_for_items

Server vs Client Components

• Server Components: Layouts, marketing pages, SEO metadata (generateMetadata, sitemap)
• Client Components: Interactive features and useQuery hooks
• Mutations: one owner per write. Server Actions for form-shaped, revalidate-only flows; TanStack Query for cache-coupled or non-form writes (resources/tech-stack.md §Mutations)

UI Implementation (Shadcn/UI)

• Usage: Prefer strict shadcn primitives (Card, Sheet, Typography, Table) over div or generic classes.
• Responsiveness: Use Drawer (mobile) vs Dialog (desktop) via useResponsive.

<!-- oma-docs:ignore-start -->

• Customization: Treat components/ui/* as read-only. Create wrappers (e.g., components/common/ProductButton.tsx) or use cva composition. Never edit components/ui/button.tsx directly.

<!-- oma-docs:ignore-end -->

Sources of Truth

• DESIGN.md (project root): visual system source of truth; read Section 9 (Agent Prompt Guide) verbatim for component prompts when present
• Design Tokens: packages/design-tokens (OKLCH); never hardcode colors
• i18n strings: packages/i18n; never hardcode UI text
• Custom utilities: check es-toolkit first; if implementing custom logic, >90% unit test coverage is mandatory

Designer Collaboration

• Sync: Map code variables to Figma layer names
• UX: Ensure key actions are visible "Above the Fold"

Stack Reference

Project stack conventions live in dedicated files. Read these before coding; they are not optional appendix material.

| File | Owns |

|---|---|

| resources/tech-stack.md | Framework versions, Next.js 16 proxy.ts + React Compiler conventions, Server Actions vs TanStack Query mutation policy, Serena shortcuts |

| resources/tailwind-rules.md | Design tokens, focus states, Tailwind v4 @theme syntax |

| resources/snippets.md | React 19 hook patterns, TanStack Query/Form, a11y card |

| resources/angular-rules.md | Angular standalone/OnPush/signals conventions, RxJS marble-test policy (MANDATORY for streams) |

To extend: add resources/<name>.md and append a row above.

References

• Follow resources/execution-protocol.md step by step.
• Before submitting, run resources/checklist.md.

Vendor-specific execution protocols are injected automatically by oma agent:spawn.

Source files live under ../_shared/runtime/execution-protocols/{vendor}.md.

• Project frontend rules (MUST load before review/implementation): ../../rules/frontend.md
• Execution steps: resources/execution-protocol.md
• Checklist: resources/checklist.md
• Error recovery: resources/error-playbook.md
• Context loading: ../_shared/core/context-loading.md
• Clarification: ../_shared/core/clarification-protocol.md
• Context budget: ../_shared/core/context-budget.md
• Lessons learned: ../_shared/core/lessons-learned.md
• Observability handoff: ../oma-observability/SKILL.md §Integrations — Core Web Vitals, SSR→client trace propagation, INP profiling

> [!IMPORTANT]

> Treat components/ui/* as read-only. Create wrappers for customization.