---
name: first-fluke/oma-frontend
source: https://app.decimal.ai/s/first-fluke-oma-frontend@3/SKILL.md
source_sha256: 7b3da2990850
---

# 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
```bash
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
1. Follow the existing React, Next.js, TypeScript, and FSD-lite architecture in the target project.
2. Use `shadcn/ui` primitives and wrappers for UI work; treat `components/ui/*` as read-only.
3. Keep server/client boundaries explicit: Server Components for static/layout work, Client Components for interaction and hooks.
4. Use project sources of truth for design tokens, i18n strings, and shared utilities before adding local alternatives.
5. Run the execution checklist before handoff and include relevant verification results.
6. **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.
7. **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`.
8. **`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.
9. **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.

1. Search: `shadcn_search_items_in_registries`
2. Review: `shadcn_get_item_examples_from_registries`
3. 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

1. Follow `resources/execution-protocol.md` step by step.
2. 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.