aragrp/docs/design-system/shadcn.md

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

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

Then immediately:

1. Open container.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

// ❌ 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
• quality-checklist.md
• Cursor rule: .cursor/rules/shadcn.mdc