jongminchungtech
KO

Maintainable Tailwind and shadcn/ui · Reference

Tailwind and shadcn/ui Maintainability Reference

Quickly look up ownership, semantic tokens, class rules, the shadcn lifecycle, and verification commands.

Verified Source

Scope

This reference targets Next.js App Router, Tailwind CSS v4, shadcn/ui base-nova, Base UI, and a pnpm monorepo.

Ownership table

QuestionOwner
Do actual light and dark values or an app font change?theme provider
Does a semantic role exposed as a utility change?token adapter
Do keyboard, focus, ARIA, or reusable visual states change?shared primitive
Do domain copy, state, and primitive composition change?product composition
Do routing, grid, container, or responsive placement change?page or feature
Is the markup controlled by a vendor?scoped integration CSS

Semantic roles

CategoryPreferred rolesCondition
surfacebackground, card, popover, muted, accentdo not use accent as a synonym for brand primary
actionprimary, secondary, destructiveprovide a foreground pair for a background role
statussuccess, warning, infoadd provider, adapter, and tests when the role recurs product-wide
product valueterminal, repository, marketingkeep it in the app theme or composition

Component selection order

  1. Inspect installed primitives and built-in variants.
  2. Compose existing primitives.
  3. Inspect the registry and current official docs.
  4. Create a recurring product composition.
  5. Add a shared primitive only when product-neutral behavior is missing.

Class rules

SituationUseAvoid
runtime statecomplete class map or cvabg-${tone}-600
runtime numbertyped CSS variable and static utilityruntime class strings
sibling spacingflex or grid gap-*repeated margins and excessive space-*
equal width and heightsize-*repeated w-* h-*
ellipsistruncatea manual three-utility combination
shared RTL-capable UIstart, end, ms, mefixed left, right, ml, mr
one-off layout formulaallow an arbitrary valueunexplained near-scale drift
raw colorrenderer allowlist onlyhex and palette utilities in consumers

cva, cn, and className

  • Use cva for closed recurring APIs such as variant, size, tone, and density.
  • Use cn for conditional classes and deliberate Tailwind conflict merging.
  • Limit consumer className to margins, width, grid or flex placement, and responsive layout.
  • Promote colors, typography, borders, shadows, internal padding, and interaction states to a variant or dedicated API.

shadcn commands

pnpm exec shadcn info --json -c apps/web
pnpm exec shadcn docs <component> -c apps/web
pnpm exec shadcn search @shadcn -q "<need>" -c apps/web
pnpm exec shadcn add <component> --dry-run -c apps/web
pnpm exec shadcn add <component> --diff <file> -c apps/web
  • Use --overwrite only for an unmodified generated-only layer or an explicit decision to discard local changes.
  • Use Base UI render and Radix asChild; do not mix the two APIs.
  • After adding a component, inspect imports, icons, accessible names, group structure, and loading states.

Tailwind v4 source contract

@import "@jongminchung/ui/globals.css";
@import "./theme.css";

@source "../**/*.{ts,tsx,mdx}";
@source not "../../.next/**/*";
  • Keep complete static class strings in scanner-visible source.
  • Register linked workspaces and components outside route trees with explicit @source entries.
  • Check required selectors in compiled production CSS.
  • Use @reference only when a separate stylesheet genuinely needs Tailwind compile context.

Verification matrix

ChangeMinimum verificationAdditional verification
utility or layoutformat, typecheck, focused testresponsive screenshot
primitive styleUI typecheck and test, consumer buildlight and dark screenshot
primitive behaviorUI test, browser interactionaffected app E2E
token or global CSStheme contract, consumer buildcontrast and visual review
source or package exportgenerated CSS contract, tarballNext.js and Vite fixtures
shadcn updatedry run, diff, UI testaccessibility and migration

Repository commands

pnpm run fmt:check
pnpm run lint
pnpm run typecheck
pnpm run test
pnpm --filter @jongminchung/web run build

Related documents

Why ownership matters

Build from scratch

Audit an existing screen

Related articles

How-to guideHow to Audit an Existing Tailwind and shadcn/ui ScreenFind ownership leaks, raw colors, dynamic classes, and risky shadcn updates, then refactor them safely.TutorialBuild a Maintainable Tailwind and shadcn/ui FeatureFollow a guided exercise to build a status panel with existing primitives and semantic tokens.ExplanationTailwind and shadcn/ui Maintainability Starts with OwnershipUnderstand why separating change authority across themes, primitives, compositions, and pages matters more than class count.