ShadCN Component Adaptation

When importing a ShadCN component into packages/ui/src/components/, apply these transformations to align with the design system.

Source of Truth

• Token recognition: @packages/ui/src/lib/classes.ts — the customTwMerge

config defines what tailwind-merge recognizes

• Token definitions: @packages/ui/src/styles/globals.css — the actual CSS

custom properties with values, line-heights, letter-spacing

• Sorting rule: @.cursor/rules/tailwind-sort.mdc — apply to any element

with >5 classes

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 globals.css.

Token Mapping (ShadCN → Design System)

Typography

See globals.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.

Other spacing tokens: inset2, inset3, inset4, inset5. See globals.css for values.

Border Radius

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

Processing Steps

1. Sort classes per the sorting rule (only if >5 classes on an element)
2. Apply typography mappings — never use text-sm, text-lg, text-xl
3. Apply spacing mappings — replace -4 with -inset
4. Apply radius mappings — use semantic radius tokens
5. Verify tokens exist in classes.ts — if you need a new token, add it

there first

Example Transformation

Before (raw ShadCN)

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

After (design system)

<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:

• No text-sm, text-lg, text-xl — use text-small, text-large,

text-xlarge

• 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