# Coding Rules

Conventions for UI code in this Next.js (App Router) + Tailwind v4 + Shadcn codebase.

## Stack assumptions

- React 19 + Next.js 16 App Router
- Tailwind CSS v4 (`@import "tailwindcss"` in `globals.css`)
- CVA + `cn()` (`clsx` + `tailwind-merge`)
- Radix-based Shadcn primitives in `components/ui/`
- Motion library: `motion/react`
- Themes: `next-themes` class strategy
- Locale: Persian RTL by default

## Always

1. Follow `docs/design-system/*` and `.cursor/rules/*`.
2. Reuse design tokens (CSS variables + Tailwind semantic colors).
3. Use `<Container>` / `layout.*` for page sections.
4. Use `type.*` or `<Typography>` for text styles.
5. Use shared `Button` and `Card` components.
6. Support light and dark themes without hardcoding surfaces.
7. Preserve responsive behavior (mobile first).
8. Preserve accessibility (focus, labels, reduced motion).
9. Prefer semantic HTML and Radix patterns already in the repo.
10. Keep components focused; extract when a pattern repeats twice+.

## Never

1. Create another content container / max-width system.
2. Hardcode colors (`#29a19c`, `rgb(…)`, `text-gray-700`) in UI.
3. Invent spacing outside the scale.
4. Duplicate Button/Card/Input styles.
5. Ship unadapted Shadcn/Tailark blocks.
6. Introduce inconsistent radii/shadows/hover timings.
7. Animate layout properties when transform suffices.
8. Commit secrets or environment files.
9. Add heavy dependencies for trivial UI.
10. Bypass ESLint without cause.

## File organization

| Kind | Location |
| --- | --- |
| Page routes | `app/**` |
| Marketing sections | `components/*.tsx` |
| Primitives | `components/ui/*` |
| Layout tokens | `lib/layout.ts` |
| Typography tokens | `lib/typography.ts` |
| Global CSS / theme | `app/globals.css` |

Name section files descriptively (`services-14.tsx`) or by domain (`footer.tsx`). Avoid `NewSection2.tsx`.

## Class composition

```tsx
import { cn } from "@/lib/utils";

className={cn(
  "section-shell bg-section-canvas",
  layout.sectionY,
  className
)}
```

- Put conditional classes in `cn`.
- Do not string-concatenate Tailwind classes manually.
- Prefer extending variants via CVA for reusable primitives.

## Imports

Use `@/` alias. Keep import groups tidy: external → `@/components` → `@/lib` → local.

## Client vs server

- Default Server Components.
- Add `"use client"` only for hooks, browser APIs, or motion/theme interactivity.
- Keep presentational children server-friendly when possible.

## State & data

- Follow existing form patterns (`react-hook-form` + zod).
- Do not fetch in deeply nested presentational components if a parent already owns data.

## Comments

- Comment only non-obvious intent (animation thresholds, RTL quirks, token constraints).
- Do not narrate obvious JSX.

## Related

- [shadcn.md](./shadcn.md)
- [quality-checklist.md](./quality-checklist.md)