gracefullight/pkgs / .agents/skills/oma-frontend
oma-frontend
UnverifiedImplement or modify web UI in React, Next.js, or Angular. Use for components, pages, styles, forms, and frontend state or data flows.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.0 KB |
| resources/angular-rules.md | markdown | 4.9 KB |
| resources/checklist.md | markdown | 4.7 KB |
| resources/component-template.tsx | other | 2.1 KB |
| resources/error-playbook.md | markdown | 5.2 KB |
| resources/examples.md | markdown | 2.1 KB |
| resources/execution-protocol.md | markdown | 2.6 KB |
| resources/snippets.md | markdown | 11.6 KB |
| resources/tailwind-rules.md | markdown | 2.7 KB |
| resources/tech-stack.md | markdown | 8.4 KB |
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |