ShadCN Component Adaptation

When importing a ShadCN component into a UI components directory (for example src/components/ui/ or packages/ui/src/components/), apply these transformations to align with the design system.

Source of Truth

•Token recognition: */lib/classes.ts — the customTwMerge config defines what tailwind-merge recognizes
•Token definitions: */styles/vars.css + */styles/index.css — CSS custom properties and @theme aliases for text, radius, spacing
•Sorting rule: .cursor/rules/tailwind-sort.mdc — apply to any element with >5 classes

Repo notes (DataConnect)

•Token recognition: src/lib/classes.ts
•Tokens + @theme aliases: src/styles/vars.css, src/styles/index.css
•classes.ts currently registers inset as a custom spacing token; add any additional inset* tokens there before use.

Why This Matters

Tailwind's built-in text-sm, text-lg, text-xl have hardcoded line-heights that don't match our design system. Our semantic tokens (text-small, text-large, text-xlarge) include proper --line-height and --letter-spacing definitions in vars.css. We also alias the Tailwind sizes to these semantic tokens in @theme, but prefer the semantic names for clarity.

Token Mapping (ShadCN → Design System)

Typography

ShadCN	Design System
`text-xs`	`text-fine`
`text-sm`	`text-small`
`text-base`	`text-body` or `text-button` (app-dependent)
`text-lg`	`text-large`
`text-xl`	`text-xlarge`
`text-2xl`	`text-heading`
`text-3xl`	`text-subtitle`
`text-4xl`	`text-title`

See vars.css and index.css for actual values and associated line-heights/letter-spacing.

Spacing (the -4 rule)

Replace Tailwind's -4 spacing with -inset for consistent internal component spacing.

ShadCN Pattern	Design System
`p-4`, `px-4`, `py-4`, `pt-4`, `pb-4`, `pl-4`, `pr-4`	`p-inset`, `px-inset`, `py-inset`, `pt-inset`, `pb-inset`, `pl-inset`, `pr-inset`
`m-4`, `mx-4`, `my-4`, `mt-4`, `mb-4`, `ml-4`, `mr-4`	`m-inset`, `mx-inset`, `my-inset`, `mt-inset`, `mb-inset`, `ml-inset`, `mr-inset`
`gap-4`	`gap-inset`
`space-x-4`, `space-y-4`	`space-x-inset`, `space-y-inset`

Other spacing tokens must be registered in classes.ts before use.

Border Radius

ShadCN	Design System
`rounded-sm`	`rounded-button`
`rounded-md`	`rounded-card`
`rounded-lg`	`rounded-squish`
`rounded-xl`	`rounded-dialog`

Also available: rounded-soft. See vars.css for values.

Processing Steps

•Sort classes per the sorting rule (only if >5 classes on an element)
•Apply typography mappings — prefer semantic text-* tokens; treat Tailwind aliases (text-sm, text-lg, text-xl) as legacy
•Apply spacing mappings — replace -4 with -inset
•Apply radius mappings — use semantic radius tokens
•Verify tokens exist in classes.ts — if you need a new token, add it there first
•If repeated typography overrides appear in call sites, create a wrapper per shadcn-primitives-wrappers

Example Transformation

Before (raw ShadCN)

tsx

<div className="flex items-center gap-4 rounded-md p-4 text-sm font-medium transition-colors hover:bg-accent">

After (design system)

tsx

<div
  className={cn(
    // layout
    "flex items-center gap-inset",
    // shape
    "rounded-card p-inset",
    // typography
    "text-small font-medium",
    // hover
    "hover:bg-accent",
    // transitions
    "transition-colors"
  )}
>

Checklist

Before committing a ShadCN component adaptation:

• Prefer text-small, text-large, text-xlarge over Tailwind aliases
• No -4 spacing — use -inset variants
• No rounded-sm, rounded-md, rounded-lg — use semantic radius tokens
• Classes sorted and commented (if >5 classes)
• Any new tokens added to classes.ts
• Wrapper created when product semantics are needed