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)
<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:
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: tailwind-shadcn-adaptation3description: When importing a ShadCN component into a UI components directory (for example Use when this capability is needed.4---56# ShadCN Component Adaptation78When importing a ShadCN component into a UI components directory (for example9`src/components/ui/` or `packages/ui/src/components/`), apply10these transformations to align with the design system.1112## Source of Truth1314- **Token recognition**: `*/lib/classes.ts` — the `customTwMerge`15 config defines what tailwind-merge recognizes16- **Token definitions**: `*/styles/vars.css` + `*/styles/index.css` — CSS custom17 properties and `@theme` aliases for text, radius, spacing18- **Sorting rule**: `.cursor/rules/tailwind-sort.mdc` — apply to any element19 with >5 classes2021### Repo notes (DataConnect)2223- Token recognition: `src/lib/classes.ts`24- Tokens + `@theme` aliases: `src/styles/vars.css`, `src/styles/index.css`25- `classes.ts` currently registers `inset` as a custom spacing token; add any26 additional `inset*` tokens there before use.2728## Why This Matters2930Tailwind's built-in `text-sm`, `text-lg`, `text-xl` have **hardcoded31line-heights** that don't match our design system. Our semantic tokens32(`text-small`, `text-large`, `text-xlarge`) include proper `--line-height` and33`--letter-spacing` definitions in vars.css. We also alias the Tailwind sizes to34these semantic tokens in `@theme`, but prefer the semantic names for clarity.3536## Token Mapping (ShadCN → Design System)3738### Typography3940| ShadCN | Design System |41| ----------- | -------------------------------------------- |42| `text-xs` | `text-fine` |43| `text-sm` | `text-small` |44| `text-base` | `text-body` or `text-button` (app-dependent) |45| `text-lg` | `text-large` |46| `text-xl` | `text-xlarge` |47| `text-2xl` | `text-heading` |48| `text-3xl` | `text-subtitle` |49| `text-4xl` | `text-title` |5051See `vars.css` and `index.css` for actual values and associated line-heights/letter-spacing.5253### Spacing (the -4 rule)5455Replace Tailwind's `-4` spacing with `-inset` for consistent internal component56spacing.5758| ShadCN Pattern | Design System |59| ----------------------------------------------------- | --------------------------------------------------------------------------------- |60| `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` |61| `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` |62| `gap-4` | `gap-inset` |63| `space-x-4`, `space-y-4` | `space-x-inset`, `space-y-inset` |6465Other spacing tokens must be registered in `classes.ts` before use.6667### Border Radius6869| ShadCN | Design System |70| ------------ | ---------------- |71| `rounded-sm` | `rounded-button` |72| `rounded-md` | `rounded-card` |73| `rounded-lg` | `rounded-squish` |74| `rounded-xl` | `rounded-dialog` |7576Also available: `rounded-soft`. See `vars.css` for values.7778## Processing Steps79801. **Sort classes** per the sorting rule (only if >5 classes on an element)812. **Apply typography mappings** — prefer semantic `text-*` tokens; treat82 Tailwind aliases (`text-sm`, `text-lg`, `text-xl`) as legacy833. **Apply spacing mappings** — replace `-4` with `-inset`844. **Apply radius mappings** — use semantic radius tokens855. **Verify tokens exist** in `classes.ts` — if you need a new token, add it86 there first876. **If repeated typography overrides appear in call sites**, create a wrapper88 per `shadcn-primitives-wrappers`8990## Example Transformation9192### Before (raw ShadCN)9394```tsx95<div className="flex items-center gap-4 rounded-md p-4 text-sm font-medium transition-colors hover:bg-accent">96```9798### After (design system)99100```tsx101<div102 className={cn(103 // layout104 "flex items-center gap-inset",105 // shape106 "rounded-card p-inset",107 // typography108 "text-small font-medium",109 // hover110 "hover:bg-accent",111 // transitions112 "transition-colors"113 )}114>115```116117## Checklist118119Before committing a ShadCN component adaptation:120121- [ ] Prefer `text-small`, `text-large`, `text-xlarge` over Tailwind aliases122- [ ] No `-4` spacing — use `-inset` variants123- [ ] No `rounded-sm`, `rounded-md`, `rounded-lg` — use semantic radius tokens124- [ ] Classes sorted and commented (if >5 classes)125- [ ] Any new tokens added to `classes.ts`126- [ ] Wrapper created when product semantics are needed127128---129> Converted and distributed by [TomeVault](https://tomevault.io/claim/vana-com) — claim your Tome and manage your conversions.130<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io