frontend — Claude Code rule: React/Next.js standards
frontend — a rule for React and Next.js projects: shadcn/ui components, Tailwind CSS v4, FSD-lite architecture, Server Components by default.
MIT ★ 1,472 updated 2026-10-29
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agentWhat frontend does
This rule enforces coding standards for React and Next.js frontends. It uses shadcn/ui components as the UI foundation and extends them through cva variants and composition instead of custom CSS. Server Components by default, Client Components only for interactivity and API calls. Semantic HTML, ARIA labels, and keyboard navigation are mandatory.
FSD-lite architecture: shared code in src/, features in src/features/[feature]/ with no cross-feature imports. File names in kebab-case follow <domain>-<role>.tsx for components, <domain>.<kind>.ts for everything else. Grab-bag names like index.tsx, utils.ts, or helpers.ts are banned. Absolute imports via @/, import type required for types.
The rule applies only to **/*.{tsx,jsx,css,scss} files and only when explicitly invoked. It needs no FFmpeg, Python, or external APIs — just a set of conventions for your IDE.
What it helps with
- enforce consistent code style across a React/Next.js team
- ban prop drilling beyond three levels
- stop developers from creating grab-bag files like utils.ts
- default to Server Components for performance
- validate accessibility in every component during review
Example prompts for the agent
- Add a product card using shadcn/ui Card and put it in
src/features/catalog/components/product-card.tsx - Refactor this hook into
use-cart-sync.ts, move Jotai atoms tocart.atoms.ts - Check that
OrderSummaryCardhas ARIA labels and keyboard navigation
How to install frontend
1Plugin marketplace
/plugin marketplace add first-fluke/oh-my-agent/plugin install oma@oh-my-agent2Manually: put the files in place
.claude/rules/frontend.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/frontend.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/frontend.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/frontend.mdManually: put the files in place
.clinerules/frontend.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about frontend
How to install frontend in Claude Code?
Run /plugin marketplace add first-fluke/oh-my-agent, then /plugin install oma@oh-my-agent. The rule will appear in .claude/rules/frontend.md.
What does the frontend rule do?
It enforces coding standards for React and Next.js: shadcn/ui components, Tailwind CSS v4, FSD-lite architecture, Server Components by default, consistent file naming, and a ban on grab-bag modules.
Why are utils.ts and helpers.ts files banned?
Grab-bag names hide what a module does. The rule requires domain and role in every filename: format-price.ts, cart.atoms.ts, orders.queries.ts.
Source text
frontend.md · MIT
---
description: React/Next.js frontend coding standards with shadcn/ui, Tailwind CSS v4, and FSD-lite architecture
globs: "**/*.{tsx,jsx,css,scss}"
alwaysApply: false
---
# Frontend Coding Standards
## Core Rules
Apply framework-specific rules only to that framework. Existing project choices take precedence over starter defaults; scoped changes do not authorize migrations.
1. **Component Reuse**: Use `shadcn/ui` components first. Extend via `cva` variants or composition. Avoid custom CSS.
2. **Design Fidelity**: Code must map 1:1 to `DESIGN.md` (Section 9 — Agent Prompt Guide) and Design Tokens. Resolve discrepancies before implementation.
3. **Rendering Strategy**: Default to Server Components for performance. Use Client Components only for interactivity and API integration.
4. **Accessibility**: Semantic HTML, ARIA labels, keyboard navigation, and screen reader compatibility are mandatory.
5. **Tool First**: Check for existing solutions and tools before coding.
7. **Request proxy convention**: when the target project uses Next.js 16+ with `proxy.ts`, preserve that convention. Check the installed framework version and routing before recommending a file rename. Diagnose wiring from code and tests.
7. **No Prop Drilling**: Avoid passing props beyond 3 levels. Use the project's client-state library (Jotai atoms or a Zustand store — see oma-frontend `resources/tech-stack.md`) instead. Avoid React Context.
8. **Auth Boundary**: Client code must not import database adapters or server-only auth code. Keep server-side application logic in the project's existing server boundary.
9. **Animation library**: preserve the project's existing animation library for scoped edits. For new motion-based implementations, use the `motion` package and `motion/react` imports.
10. **Framework version**: preserve the installed framework and dependency ranges for scoped changes. Select versions when scaffolding or when an upgrade is explicitly requested; do not upgrade an existing app to satisfy a starter default.
## Architecture (FSD-lite)
- **Root (`src/`)**: Shared logic (components, lib, types). Hoist common code here.
- **Feature (`src/features/*/`)**: Feature-specific logic. **No cross-feature imports.** Unidirectional flow only.
```
src/features/[feature]/
├── components/ # Feature UI components
│ └── skeleton/ # Loading skeleton components
├── types/ # Feature-specific type definitions
└── utils/ # Feature-specific utilities & helpers
```
## Naming Conventions
### Symbols
- Components/Types/Interfaces: `PascalCase`
- Functions/Vars/Hooks: `camelCase`
- Constants: `SCREAMING_SNAKE_CASE`
- Imports: Absolute `@/` is MANDATORY (no relative `../../`)
- MUST use `import type` for interfaces/types
### File Naming — self-describing names
**Principle: the filename alone must answer "what domain + what role". If a reader has to open the file to know what it is, the name is wrong.**
All files are `kebab-case`. Components use `<domain>-<ui-role>.tsx`; non-component modules use `<domain>.<kind>.ts`.
| Kind | Pattern | Example |
|------|---------|---------|
| Component | `<domain>-<ui-role>.tsx` | `order-summary-card.tsx` → `OrderSummaryCard` |
| Skeleton | `<component>-skeleton.tsx` | `order-summary-card-skeleton.tsx` |
| Hook | `use-<behavior>.ts` | `use-order-polling.ts` |
| TanStack Query | `<domain>.queries.ts` / `<domain>.mutations.ts` | `orders.queries.ts` |
| Jotai atoms | `<domain>.atoms.ts` | `cart.atoms.ts` |
| Zustand store | `<domain>.store.ts` | `cart.store.ts` |
| Zod schema | `<domain>.schema.ts` | `checkout.schema.ts` |
| Types | `<domain>.types.ts` | `order.types.ts` |
| Constants | `<domain>.constants.ts` | `payment.constants.ts` |
| API client | `<domain>.api.ts` | `orders.api.ts` |
| Utility | one capability per file, named as a verb phrase | `format-price.ts`, `parse-tracking-number.ts` |
| Test | colocated `<target>.test.ts(x)` | `format-price.test.ts` |
Rules:
1. **Filename = kebab-case of the main export.** One main export per file; `order-summary-card.tsx` exports `OrderSummaryCard`.
2. **Keep the domain in the name even inside a feature directory.** Editor tabs and search results show only the basename — `cart-summary-card.tsx`, not `summary-card.tsx` inside `features/cart/components/`.
3. **`index.ts` only as a feature public-API barrel** (`src/features/<feature>/index.ts`). Never `index.tsx` as a component file.
4. **Grab-bag filenames are BANNED**: `utils.ts`, `helpers.ts`, `common.ts`, `misc.ts`, `data.ts`, `styles.ts`, and bare `types.ts` / `constants.ts` / `hooks.ts` without a domain prefix. Split them by domain or capability instead.
5. **Version/status suffixes are BANNED**: `*-v2`, `*-new`, `*-old`, `*-final`, `*-copy`, `*-refactored`. Git owns history, not filenames.
6. **No abbreviations** beyond universally known ones (`api`, `db`, `i18n`, `a11y`): `user-profile-card.tsx`, never `usr-prf-crd.tsx`.
## Performance
- Target First Contentful Paint (FCP) < 1s
- Use `next/dynamic` for heavy components, `next/image` for media
- Responsive Breakpoints: 320px, 768px, 1024px, 1440px
© First Fluke · MIT · first-fluke/oh-my-agent