Skip to content

gracefullight/pkgs / .agents/skills/oma-frontend

oma-frontend

Unverified

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

resources/tech-stack.md

View on GitHub
# Frontend Agent - Tech Stack Reference

These are defaults for new projects without an established stack. Preserve the target project's installed versions and conventions; a scoped feature or fix does not authorize a stack migration.

## Core Framework
- **Framework**: Next.js 16+ (App Router), React 19+
- **Language**: TypeScript (strict mode)
- **Testing**: Vitest, React Testing Library
- **Browser verification**: Browser verification uses the installed MCPs selected in `mcp.devtools_browsers`: Aside (`aside`, default), Chrome DevTools MCP (`chrome`), and Firefox DevTools MCP (`firefox`). Multiple selections are supported; use `oma update mcp` to change them. Discover the selected server’s actual tools before use; tool names and capabilities differ between servers. An empty selection disables browser MCP verification; report any unverified UI checks.
- **UI**: `shadcn/ui` on the **Base UI** engine (see below)

## shadcn/ui Primitive Engine — Base UI vs Radix

shadcn/ui ships on two interchangeable headless engines: **Radix UI** and **Base UI**
(by the MUI team). Every component has parity docs/examples on both, and the public
component API is identical — only the underlying primitive changes.

### How the engine is selected

The engine is **not** a standalone `components.json` field. It is encoded in the **`style`**
prefix:

| `style` value | Engine |
|---|---|
| `base-*` (e.g. `base-vega`) | **Base UI** |
| `radix-*` (e.g. `radix-nova`) | Radix UI |

```jsonc
// components.json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-vega",        // <- engine + style; base-* = Base UI
  "rsc": true,
  "tsx": true,
  "tailwind": { "css": "src/styles/globals.css", "baseColor": "neutral", "cssVariables": true },
  "iconLibrary": "lucide",
  "aliases": { /* ... */ }
}
```

Bootstrap with `npx shadcn create` (prompts for the engine) or `npx shadcn init`.

### Project default: **Base UI**

1. **New projects MUST default to Base UI** (`style: "base-*"`). Rationale: Radix slowed after
   the WorkOS acquisition; Base UI is under active development with smaller bundles and is the
   more future-proof bet. The API is identical, so there is no DX cost.
2. **Radix is an allowed fallback** — keep `radix-*` for an existing Radix codebase, or when a
   needed component is only stable on Radix. State the reason when choosing Radix.
3. **Do NOT big-bang migrate** an existing project to Base UI just because it is the default.
   Migrate component-by-component, with reason; due to API differences a global swap is risky.
4. To switch engines: change the `style` prefix, then re-add base components with
   `npx shadcn add button card dialog … --overwrite`. Treat `components/ui/*` as read-only
   otherwise (customize via wrappers / `cva`).

## Next.js 16 Conventions

### Proxy replaces Middleware

For projects using the Next.js 16+ proxy convention, preserve `proxy.ts`. Check the installed framework version and existing routing before proposing a migration.

- File: `middleware.ts` → `proxy.ts` (root or `src/`)
- Exported function: `middleware` → `proxy`
- Config flags: `skipMiddlewareUrlNormalize` → `skipProxyUrlNormalize`, etc.
<!-- oma-docs:ignore-start -->
- `src/proxy.ts` is the canonical request-proxy / auth-gate location
<!-- oma-docs:ignore-end -->

Do not infer that a framework entry point is unused from missing imports alone. Verify its location, exports, configuration, and relevant tests before reporting a wiring defect.

Reference: https://nextjs.org/docs/messages/middleware-to-proxy

### React Compiler (stable in Next.js 16)

Next.js 16 supports the React Compiler as a **stable, opt-in** top-level option (disabled by
default). It auto-memoizes components, replacing most manual memoization.

```ts
// next.config.ts (requires `babel-plugin-react-compiler` as a devDependency)
const nextConfig: NextConfig = {
  reactCompiler: true, // or { compilationMode: 'annotation' } for opt-in per component
}
```

Rules:

1. **Check whether the project has it enabled before tuning renders.** Look for
   `reactCompiler` in `next.config.*`.
2. **Compiler ON**: do NOT hand-write `useMemo` / `useCallback` / `React.memo` in new code;
   the compiler owns memoization. Correct `useEffect` deps still matter (the compiler does
   not fix dependency bugs).
3. **Compiler OFF**: memoize manually as usual; suggest enabling the compiler only as a
   separate, explicit change (it adds Babel to the build and increases compile times).
4. Do not mix modes ad hoc: `'annotation'` mode means only `"use memo"`-annotated components
   compile; don't assume whole-app coverage.

## Server State — orval-generated TanStack Query hooks

When the project has an OpenAPI spec (most oma projects do), **TanStack Query hooks are
generated by `orval`, not hand-written**. The pipeline lives in oma-dev-workflow
(`resources/api-workflows.md`): backend emits `openapi.json` → `bunx orval` (usually via
`mise run gen:api`) emits typed `useQuery`/`useMutation` hooks (`client: react-query`).

1. **Generated output is read-only**, same rule as `components/ui/*`. Never edit generated
   hooks/models; fix the OpenAPI spec (or orval config) and regenerate.
2. **Contract change flow**: backend schema change → regenerate spec → `bunx orval` →
   fix resulting type errors in consuming code. Don't patch types by hand to "match later".
3. **Cross-cutting concerns go in the orval `mutator`** (custom axios/fetch instance):
   auth headers, base URL, error normalization; never per-hook.
4. **Hand-written TanStack Query hooks are the exception**: third-party APIs or endpoints
   outside the spec. Follow the fallback pattern in `snippets.md` §TanStack Query Hook.

## Mutations — Server Actions vs TanStack Query

Both are legitimate write paths in Next.js 16; pick per mutation, and don't route the same
mutation through both.

| Pick | When |
|---|---|
| **Server Action** (`'use server'` + `useActionState`) | Form-shaped, page-scoped writes where progressive enhancement or zero client JS matters; simple submit → revalidate flows (`revalidatePath` / `revalidateTag`); no shared client cache to update. |
| **TanStack Query mutation** | The write must update client-cached reads (`invalidateQueries`, optimistic updates, rollback); fires outside a form (drag-drop, toggles, autosave); needs retry/queue/offline semantics or fine-grained pending UI across components. |

Guidance:

1. If the data is already read through TanStack Query, mutate through TanStack Query; a
   Server Action won't invalidate the client cache by itself.
2. Server Actions are still server endpoints: validate input with zod on the server side and
   enforce auth inside the action, never only in the UI.
3. Don't call Server Actions from TanStack Query's `mutationFn` as a default pattern; that
   stacks two mutation layers. Choose one owner per mutation.

## Client State — Jotai vs Zustand

Client state has **no project default**; pick per intent. Both are allowed, but **only one
per project** unless there is a strong reason to mix. The overriding rule is to *minimize
client state* in the first place: server state belongs in **TanStack Query**, URL state in
**nuqs**. Reach for a client-state library only for genuine client-owned state.

| Pick | When |
|---|---|
| **Jotai** | Atomic / bottom-up. Fine-grained, derived, or near-local shared state; many small independent atoms; state that maps onto React's render graph and RSC-split boundaries. |
| **Zustand** | Store / top-down. A single cohesive global store with action methods; needs non-React access (`store.getState()` / `subscribe` outside render); simpler mental model for app-wide state. |

Guidance:

1. **State the choice** in the project (e.g. a short note in the app README or DESIGN.md) so
   contributors don't introduce the other library ad hoc.
2. **Don't mix** Jotai and Zustand in one app without justification — two client-state models
   fragment the codebase.
3. **Default-free does not mean optional analysis**: if neither atomic nor single-store clearly
   fits, the state probably belongs in TanStack Query (server) or nuqs (URL), not here.

## Optional Serena examples

These examples apply only when Serena is the configured provider and its tools are available. Otherwise use the project-selected provider or native search under the shared code-intelligence contract.
- `find_symbol("ComponentName")`: locate existing component
- `get_symbols_overview("src/components")`: list all components
- `find_referencing_symbols("Button")`: find usages before changes
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall