Build assistant rules (Next.js + shadcn/ui)

1. Goal

• Deliver bespoke, production-ready pages. No generic or cookie-cutter designs.

2. Stack

• Next.js App Router + TypeScript + Tailwind CSS + shadcn/ui + React hooks.
• Icons: lucide-react only.
• Do not add UI/theme/icon libraries unless explicitly requested or strictly required.

3. Do not reinstall or overwrite

• Before any change, read package.json, package-lock.json, components.json, and the components/ui directory.
• If a dependency (and version) already exists, do not reinstall, upgrade, or downgrade.
• If a component file exists under components/ui, do not regenerate or overwrite it.
• If components.json exists, do not re-init shadcn.
• Only add missing items that are strictly required for the requested feature.
• If an overwrite or version change is truly necessary, write a short reason and the minimal diff; wait for approval.

4. Client vs server

• If a component uses useState, useEffect, browser APIs, or client-only hooks, add at the top: "use client";
• Keep server and client markup identical on first render to avoid hydration issues.

5. Prevent this warning

• Do not produce: Warning: Extra attributes from the server: "class,style"
• Avoid non-deterministic render output (Date.now, Math.random, crypto) during initial render.
• Do not change root attributes between server and client.
• Use suppressHydrationWarning only with a concrete reason.

6. UI usage

• Build with Tailwind and existing shadcn/ui components first.
• Compose from what is already present (accordion, alert, button, card, dialog, form, table, tabs, tooltip, etc.).
• Add a new shadcn component only if composition is unreasonable and only if it is missing.

7. Page quality

• Clear hierarchy and spacing, responsive at sm/md/lg, accessible (focus states, contrast AA).
• Provide empty, loading, and error states using existing skeleton, toast/sonner, progress, etc.
• Icons come from lucide-react.

8. Data and hooks

• Fetch data on the server (server components or route handlers) when possible.
• Pass stable, serializable props to client components. Keep hooks inside client components.

9. Packages and commands

• Use npm (lockfile present). Prefer npm ci when not changing deps.
• When a new dep is strictly required, pin an exact version. No bulk upgrades or removals.

10. Safe-change procedure (always)

• Inventory what exists.
• Confirm the feature can be built from existing components.
• Propose only the minimal additions. No reinstalls. No overwrites.
• Build and run: npm run build && npm run start. Ensure no TypeScript or hydration warnings.

Short examples

Do

• Create a new page with existing card, tabs, dialog, and form.
• Mark client components with "use client" when using state/effects.
• Import icons from lucide-react.

Don’t

• Re-init shadcn when components.json exists.
• Regenerate or overwrite files in components/ui.
• Add new UI kits or icon packs.