pm4ai

shadcn

shadcn component usage conventions

shadcn components used as-is, native look, semantic classes only.

MUST

  • Use shadcn components as-is. Why: no override drift.
  • Semantic Tailwind colors only — text-foreground/text-muted-foreground/text-destructive, bg-primary/bg-muted/bg-destructive, text-primary for links. Why: theme-driven, dark-mode safe.
  • cn() for conditional classes. Why: merge precedence + the only composition path.

NEVER

  • Hardcode hex / palette colors in className or style — text-red-500, bg-blue-500, text-green-500. Cost: bypasses theme.
  • fd-* aliases (bg-fd-muted, text-fd-muted-foreground, bg-fd-primary). Cost: fumadocs internals; use the shadcn name.
  • Template literal for conditional className. Cost: no merge precedence; use cn().
  • cva / bare clsx / bare twMerge. Cost: fragments the single cn() composition path.

Examples

GoodBad
cn('base', cond && 'on')`base ${cond ? 'on' : ''}`
cn('base', v === 'a' ? 'x' : 'y')clsx('base', ...) / cva(...)
bg-muted text-primarybg-fd-muted text-blue-500

Pitfall

  • global.css aliases --color-* → --color-fd-* via @theme inline, so bg-muted/text-primary/border-border resolve to the same theme as fd-* — always use the shadcn name.
  • fumadocs’ own UI (sidebar/search/TOC) keeps fd-* internally — that is library code, not yours.

Security

Security constraints — credential handling, env var scoping, server vs client boundaries

Testing

Testing conventions and strategies

On this page

MUSTNEVERExamplesPitfall