Getting Started
Components
Search for a command to run...
This document provides the standard content that should be added to every application's AGENTS.md file after initial project setup. Copy the section below and append it to your project's existing AGENTS.md.
Download: You can also download the template directly for easy copy-paste.
Before adding this section, ensure your AGENTS.md already contains:
npm run dev, npm run build, etc.)Copy everything below and append to your AGENTS.md:
---
## Design Consistency Standards
These rules ensure consistency across all applications. For detailed rationale and examples, see the centralized Design Standards Documentation.
### React Compiler Optimization
This project uses React Compiler (`babel-plugin-react-compiler`):
**DO NOT USE:**
- `useMemo()` - compiler handles memoization automatically
- `useCallback()` - compiler optimizes callback references
- `React.memo()` - rarely needed with compiler optimization
**DO USE:**
- `React.lazy()` for code splitting (unrelated to memoization)
- Standard hooks: `useState`, `useEffect`, `useRef`
---
### State Management
**Decision Tree:**
1. Is this server data (from API)? → **TanStack Query**
2. Is this component-local UI state? → **useState**
3. Is this session-level shared state (auth, tenant, theme)? → **React Context**
4. Is this complex, computed, or cross-component state? → **Zustand**
**Anti-Patterns:**
- Never store API responses in `useState`
- Never duplicate TanStack Query cache in local state
- Never create Context for single-component state
---
### Form Implementation
**Before implementing any form:**
| Condition | Solution |
| ----------------------------- | --------------------- |
| 1-3 fields AND no validation | `useState` |
| 4+ fields OR validation rules | React Hook Form + Zod |
**Complex Form Requirements:**
1. Create schema in `/schemas/{feature}-schema.ts`
2. Use `zodResolver` with React Hook Form
3. Use shadcn/ui Form components (`FormField`, `FormItem`, `FormControl`, `FormMessage`)
---
### TanStack Query
**Required Patterns:**
- Use query key factory from `hooks/query-keys.ts`
- Create custom hooks for all queries (never use `useQuery` directly in components)
- Implement optimistic updates for mutations
- Handle all three states: loading, error, empty
**Before creating a query:**
1. Check `hooks/query-keys.ts` for existing key
2. Check `/hooks/use-*.ts` for existing hook
3. Add query key first, then create hook
---
### Error Handling
**Architecture:**
| Error Type | Handler |
| --------------------- | ------------------------- |
| React component crash | Error Boundary |
| API error (expected) | Query error state + Toast |
| Validation error | Form field errors |
| Network error | Toast notification |
**Error Message Pattern:**
- APIs return error codes, not user messages
- UI maps codes to user-friendly messages via `lib/error-messages.ts`
- Never display raw API error messages to users
---
### Accessibility Requirements
**Icon-Only Buttons:**
```typescript
// REQUIRED - use aria-label
<Button variant="ghost" size="icon" aria-label="Delete project">
<Trash2 className="h-4 w-4" />
</Button>
// ALTERNATIVE - use sr-only span
<Button variant="ghost" size="icon">
<Trash2 className="h-4 w-4" />
<span className="sr-only">Delete project</span>
</Button>
// NEVER - no accessible name
<Button variant="ghost" size="icon">
<Trash2 className="h-4 w-4" />
</Button>
```Required for All Components:
alt="" for decorative)Use Skeleton when:
Use Spinner when:
Always provide:
Production builds use manual chunk splitting for optimal caching:
| Chunk | Contents |
|---|---|
vendor-react | React core, React Router |
vendor-charts | Recharts, D3 (lazy-load) |
vendor-editor | Plate.js, Slate (lazy-load) |
vendor-forms | React Hook Form, Zod |
vendor-query | TanStack Query |
vendor-radix | Radix UI primitives |
vendor-utils | date-fns, clsx, Lucide |
vendor-auth | OIDC authentication |
Heavy chunks (vendor-charts, vendor-editor) should be lazy-loaded with React.lazy().
Before completing any component:
readonly modifieraria-labelcn() for conditional classes@/ import aliasesBranch Naming:
main^(feature|hotfix)\/[a-z0-9\-]+$Preferred Formats:
| Type | Pattern | Example |
|---|---|---|
| Feature with ticket | feature/ticket-####-description | feature/ticket-1234-add-user-auth |
| Feature without ticket | feature/description | feature/add-dark-mode |
| Hotfix with ticket | hotfix/ticket-####-description | hotfix/ticket-5678-fix-login-bug |
| Hotfix without ticket | hotfix/description | hotfix/fix-null-pointer |
Branch Rules:
feature/ - New features, enhancements, refactoringhotfix/ - Bug fixes, urgent patchesCommit Guidelines:
Pull Request Requirements:
When adding this section to a project, you may need to customize:
Bundle Chunking Table - Adjust based on project dependencies (remove unused chunks, add project-specific ones)
Query Key Location - If your project uses a different path for query keys, update the reference
Schema Location - If schemas are stored elsewhere, update /schemas/ references
Error Messages Location - Update lib/error-messages.ts path if different
React Compiler - If the project doesn't use React Compiler, remove that section and add guidance for manual memoization
After adding the section, verify:
--- separatorvite.config.ts