aragrp/docs/design-system/coding-rules.md

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

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
• quality-checklist.md