Skip to content
agent-skills

shadcn Theming Tokens And Dark Mode

Pack: shadcn Source: shadcn/shadcn-theming-tokens-and-dark-mode/SKILL.md Use this skill when the task is mainly about visual defaults, token strategy, or dark-mode behavior in a shadcn app.

Scope

Section titled “Scope”
  • theme tokens
  • CSS variables mode
  • semantic color mapping
  • dark mode strategy
  • keeping component-level styling overrides under control

Routing cues

Section titled “Routing cues”
  • shadcn theming, :root, CSS variables, OKLCH colors, semantic tokens, dark mode, theme provider, next-themes, or visual consistency across components -> use this skill
  • if the work is mainly about CLI init or components.json -> use shadcn-cli-registry-and-components-json
  • if the work is mainly about component composition and trigger behavior -> use shadcn-composition-and-trigger-patterns

Default path

Section titled “Default path”
  1. Use CSS variables mode for app-wide theming.
  2. Define semantic tokens first: background, foreground, card, popover, primary, secondary, muted, accent, border, input, ring, and chart or sidebar tokens if the app needs them.
  3. Keep brand decisions in token values, not repeated utility overrides inside every component.
  4. Use one dark-mode strategy for the whole app and wire it early.
  5. Let components consume tokens through their default class contracts before adding custom variants.

When to deviate

Section titled “When to deviate”
  • Use hardcoded per-component utility styling only when the component is intentionally one-off.
  • Add extra token families only when a repeated product surface truly needs them.
  • Skip dark mode only when the product has a deliberate single-theme stance.

Guardrails

Section titled “Guardrails”
  • tokens should describe semantics, not page-specific hacks
  • brand color changes belong in variables, not in mass component edits
  • dark mode should be an application decision, not a component-by-component experiment
  • keep contrast and readability intact when shifting tokens

Avoid

Section titled “Avoid”
  • styling every shadcn component with ad hoc utility overrides instead of fixing the token layer
  • creating token names that encode one page or one feature
  • adding several parallel dark-mode patterns in the same app
  • using theme state to solve layout or composition problems

Verification checklist

Section titled “Verification checklist”
  • the app has one coherent token layer instead of scattered one-off colors
  • dark mode is configured once and applied consistently
  • component styling changes mostly come from tokens or a small number of variants
  • semantic token names still make sense after the customization

Current snapshot

Section titled “Current snapshot”
  • Checked against official docs on 2026-04-03
  • Current npm line verified live on 2026-04-03: shadcn@4.1.2
  • Docs in scope: theming and dark mode

Official references

Section titled “Official references”

References

Section titled “References”