# Shadcn / Tailark Adaptation

Imported blocks are starting points—not finished UI. Every Shadcn UI or Tailark block must be adapted to Amin Rayan tokens before merge.

## Goals

- Visual continuity with existing sections.
- One container, one spacing scale, one button/card system.
- Dark mode and RTL friendliness preserved.

## Adaptation checklist (mandatory)

When adding or regenerating a block:

1. **Container** — Replace `container`, `mx-auto max-w-*`, and foreign `px-*` with `<Container>` / `layout.container`.
2. **Section rhythm** — Outer `<section>` uses `layout.sectionY` (+ `section-shell` / `bg-section-*` as appropriate).
3. **Colors** — Remap to semantic tokens (`bg-background`, `text-foreground`, `primary`, `muted-foreground`, `border`). Delete purple/zinc hardcodes.
4. **Typography** — Swap ad-hoc heading classes for `type.*` / `<Typography>`.
5. **Buttons** — Use `@/components/ui/button` only; map sizes to `sm | default | lg`.
6. **Cards** — Prefer `@/components/ui/card`; remove stacked shadow recipes that fight `shadow-sm`.
7. **Radius** — Align to `--radius` scale (`rounded-md`, `rounded-xl`, `rounded-blog` where relevant).
8. **Shadows** — Prefer `shadow-xs` / `shadow-sm` / `shadow-md` / `shadow-glow-primary`.
9. **Motion** — Prefer `MotionReveal` or existing duration scale; strip flashy infinite animations unless product-required.
10. **Dark mode** — Verify `.dark` with semantic tokens; remove `dark:` hacks that reintroduce foreign palettes.
11. **A11y** — Keep Radix behaviors; ensure labels, focus, and reduced motion.
12. **Alignment QA** — Compare left/right edges with header/footer.

## Never allow after import

| Banned | Replace with |
| --- | --- |
| Random containers / `max-w-5xl` shells | `<Container>` |
| Random hex colors | Semantic tokens |
| Random typography stacks | `type.*` |
| Parallel button CSS | `Button` |
| Arbitrary spacing (`p-[1.125rem]`) | Spacing scale |
| Purple / indigo marketing gradients | Brand gradients |
| Extra global CSS for one block | Local Tailwind + existing utilities |

## Workflow

```bash
npx shadcn@latest add button
# or paste a Tailark section into components/
```

Then immediately:

1. Open [container.md](./container.md) + [quality-checklist.md](./quality-checklist.md).
2. Diff the block against a known-good section (`services-14`, `cta-16`, `footer`).
3. Delete unused vendor CSS variables.
4. Wire copy to Persian where the surface is fa-IR.

## Example transform

```tsx
// ❌ Vendor
<section className="py-24">
  <div className="mx-auto max-w-5xl px-4">
    <h2 className="text-4xl font-bold tracking-tight">…</h2>
    <button className="rounded-full bg-indigo-600 px-6 py-3 text-white">…</button>
  </div>
</section>

// ✅ Adapted
<section className={cn("section-shell bg-section-canvas", layout.sectionY)}>
  <Container>
    <h2 className={type.h2}>…</h2>
    <Button size="lg">…</Button>
  </Container>
</section>
```

## Existing UI primitives

Prefer composing from `components/ui/*` already in the repo (59+ primitives) instead of re-adding duplicates.

## Related

- [coding-rules.md](./coding-rules.md)
- [quality-checklist.md](./quality-checklist.md)
- Cursor rule: `.cursor/rules/shadcn.mdc`