Theming

The tokens every component is styled with, and how dark mode switches them.

The theme sets shadcn's standard color variables, so other shadcn components match. It lives in your CSS, and changing a token there changes every component that uses it.

Dark mode

Every token has a dark value, used inside any element with the dark class, where Tailwind's dark: variant applies too. The theme also sets color-scheme: dark there, so scrollbars and native form controls follow.

Put the class on <html> to switch the whole page. It has to be there before the page first paints, or a dark page flashes light as it loads, so a script at the top of <head> sets it from the reader's stored choice, or from the system setting until they make one. A provider then stores each new choice and, while it's System, follows the system setting as it changes.

Below are setups for Next.js and Vite. For other frameworks, such as Astro, Remix and TanStack Start, follow shadcn's dark mode guides, which set the same class.

Next.js

next-themes does both. Install it.

pnpm add next-themes

Wrap the root layout in its ThemeProvider, and add suppressHydrationWarning to <html>, since its script changes the class before React hydrates.

app/layout.tsx

import { ThemeProvider } from "next-themes";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="class"
          defaultTheme="system"
          enableSystem
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

disableTransitionOnChange turns transitions off for the moment the theme switches, so controls change color at once rather than fading one by one.

Vite

Add the script to <head> in index.html, before anything that renders. It falls back to the system setting when nothing valid is stored, and leaves the page alone if storage is blocked.

index.html

<script>
  (function () {
    try {
      var theme = localStorage.getItem("theme");
      if (theme !== "light" && theme !== "dark" && theme !== "system") theme = "system";
      var dark = matchMedia("(prefers-color-scheme: dark)").matches;
      var resolved = theme === "system" ? (dark ? "dark" : "light") : theme;
      var root = document.documentElement;
      root.classList.add(resolved);
      root.style.colorScheme = resolved;
    } catch (e) {}
  })();
</script>

Then add a provider, and wrap the app in it.

components/theme-provider.tsx

import * as React from "react";

type Theme = "light" | "dark" | "system";

const ThemeContext = React.createContext<{
  theme: Theme;
  setTheme: (theme: Theme) => void;
} | null>(null);

function isTheme(value: unknown): value is Theme {
  return value === "light" || value === "dark" || value === "system";
}

function applyTheme(theme: Theme) {
  const dark = matchMedia("(prefers-color-scheme: dark)").matches;
  const resolved = theme === "system" ? (dark ? "dark" : "light") : theme;
  const root = document.documentElement;
  root.classList.remove("light", "dark");
  root.classList.add(resolved);
  root.style.colorScheme = resolved;
}

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setThemeState] = React.useState<Theme>(() => {
    const stored = localStorage.getItem("theme");
    return isTheme(stored) ? stored : "system";
  });

  React.useEffect(() => {
    applyTheme(theme);
    if (theme !== "system") return;
    const media = matchMedia("(prefers-color-scheme: dark)");
    const onChange = () => applyTheme("system");
    media.addEventListener("change", onChange);
    return () => media.removeEventListener("change", onChange);
  }, [theme]);

  const value = React.useMemo(
    () => ({
      theme,
      setTheme: (next: Theme) => {
        localStorage.setItem("theme", next);
        setThemeState(next);
      },
    }),
    [theme],
  );

  return <ThemeContext value={value}>{children}</ThemeContext>;
}

export function useTheme() {
  const context = React.useContext(ThemeContext);
  if (!context) throw new Error("useTheme must be used within a ThemeProvider");
  return context;
}

It stores the choice under theme, the key next-themes uses too.

Toggle

A Dropdown Menu with a radio item for each choice lets readers pick one, and shows which is set. The trigger's icon follows the page with the dark: variant, so it's right before the provider knows the choice. Import useTheme from next-themes in Next.js, or from @/components/theme-provider with the Vite provider. Both return the theme and setTheme it uses.

components/mode-toggle.tsx

"use client";

import { MoonIcon, SunIcon } from "lucide-react";

import { useTheme } from "@/components/theme-provider";
import { Button } from "@/components/ui/button";
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";

export function ModeToggle() {
  const { theme, setTheme } = useTheme();
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="ghost" size="icon" aria-label="Theme" />}>
        <SunIcon className="dark:hidden" />
        <MoonIcon className="hidden dark:block" />
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end">
        <DropdownMenuRadioGroup value={theme} onValueChange={setTheme}>
          <DropdownMenuRadioItem value="light">Light</DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="dark">Dark</DropdownMenuRadioItem>
          <DropdownMenuRadioItem value="system">System</DropdownMenuRadioItem>
        </DropdownMenuRadioGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

Tokens

Alongside shadcn's variables, the theme adds these.

Tokens	Use
`layer-1` … `layer-4`	Stepped surfaces, from raised panels to tracks.
`faint`	Tertiary text, quieter than `muted-foreground`.
`icon`, `icon-muted`	Icon colors.
`border-muted`, `border-strong`	Lighter and heavier hairlines.
`hover`, `pressed`	Translucent overlays for interactive states.
`primary-hover`, `primary-pressed`	The same overlays, for primary buttons.
`scrim`	The backdrop behind dialogs and sheets.
`link`	Link text.
`brand`, `brand-foreground`	The accent on checked controls, sliders and progress.
`knob`, `knob-checked`	Knobs on switches and sliders, and the dot in a checked radio.
`success`, `warning`, `info`, `destructive`	State colors. Each has `-muted` (a tinted surface) and `-border` companions.
`syntax-property`, `-string`, `-number`, `-constant`, `-function`, `-keyword`	Code: keys, strings, numbers, constants such as `true`, functions and keywords.
`shadow-raised`, `-floating`, `-overlay`	Elevation for cards, popovers and dialogs.
`shadow-button`, `-button-primary`, `-elements`, `-switch-off`, `-switch-on`	Elevation for controls.
`palette-*`	The color scales behind the tokens.

Colors

Every color token in light and dark mode. Values such as grey-50 are steps of the palette. Hover a swatch to see the color it resolves to.

Surfaces

Token	Light	Dark
`background`	`grey-50`#fff	`grey-1100`#161616
`card`	`grey-100`#fafafa	`grey-1000`#242424
`popover`	`grey-100`#fafafa	`grey-1000`#242424
`muted`	`grey-200`#f2f2f2	`grey-900`#2e2e2e
`layer-1`	`grey-100`#fafafa	`grey-1000`#242424
`layer-2`	`grey-200`#f2f2f2	`grey-900`#2e2e2e
`layer-3`	`grey-300`#eee	`grey-800`#3a3a3a
`layer-4`	`grey-400`#dbdbdb	`grey-700`#5c5c5c

Text and icons

Token	Light	Dark
`foreground`	`grey-1100`#161616	`grey-100`#fafafa
`card-foreground`	`grey-1100`#161616	`grey-100`#fafafa
`popover-foreground`	`grey-1100`#161616	`grey-100`#fafafa
`muted-foreground`	`grey-700`#5c5c5c	`grey-500`#aeaeae
`faint`	`grey-600`#808080	`grey-600`#808080
`link`	`blue-600`#3b5cf6	`blue-400`#a2bcff
`icon`	`grey-800`#3a3a3a	`grey-400`#dbdbdb
`icon-muted`	`grey-600`#808080	`grey-600`#808080

Borders

Token	Light	Dark
`border`	`#0000001a`	`#ffffff1a`
`border-muted`	`#00000014`	`#ffffff14`
`border-strong`	`#00000033`	`#ffffff33`
`input`	`#0000001a`	`#ffffff1a`
`ring`	`blue-500`#7698fd	`blue-500`#7698fd

Controls

Token	Light	Dark
`primary`	`grey-1000`#242424	`grey-700`#5c5c5c
`primary-foreground`	`grey-50`#fff	`grey-50`#fff
`secondary`	`grey-50`#fff	`#ffffff0f`
`secondary-foreground`	`grey-1100`#161616	`grey-100`#fafafa
`accent`	`#0000000a`	`#ffffff0f`
`accent-foreground`	`grey-1100`#161616	`grey-100`#fafafa
`brand`	`blue-600`#3b5cf6	`blue-600`#3b5cf6
`brand-foreground`	`grey-50`#fff	`grey-50`#fff
`knob`	`grey-200`#f2f2f2	`grey-200`#f2f2f2
`knob-checked`	`grey-300`#eee	`grey-300`#eee

Overlays

Overlays are translucent. primary-hover and primary-pressed are shown over primary.

Token	Light	Dark
`hover`	`#0000000a`	`#ffffff0f`
`pressed`	`#00000014`	`#ffffff1a`
`primary-hover`	`#ffffff1f`	`#0000003d`
`primary-pressed`	`#ffffff3d`	`#00000066`
`scrim`	`#00000066`	`#00000099`
`skeleton`	`#0000000f`	`#ffffff0f`
`skeleton-shine`	`#ffffff80`	`#ffffff0a`

States

Token	Light	Dark
`success`	`green-800`#198b43	`green-500`#6bd586
`success-muted`	`green-100`#e7f9ea	`green-1200`#14361d
`success-border`	`green-300`#b8e9c1	`green-900`#1d783c
`warning`	`yellow-800`#cb9f34	`yellow-500`#f2cf76
`warning-muted`	`yellow-100`#fefaec	`yellow-1200`#4b4025
`warning-border`	`yellow-300`#f7e5b5	`yellow-900`#ac8833
`info`	`blue-800`#2c47c8	`blue-500`#7698fd
`info-muted`	`blue-100`#ecf1fe	`blue-1200`#1b2852
`info-border`	`blue-300`#c3d4fd	`blue-900`#263fa9
`destructive`	`red-800`#b82d35	`red-500`#f17471
`destructive-muted`	`red-100`#fceceb	`red-1200`#461516
`destructive-border`	`red-300`#f2bbb7	`red-900`#97252b

Syntax

Colors for code, such as the keys and values in JSON Viewer. They're GitHub Light's and GitHub Dark's, as in the code blocks on this site.

Token	Light	Dark
`syntax-property`	`#005cc5`	`#79b8ff`
`syntax-string`	`#032f62`	`#9ecbff`
`syntax-number`	`#005cc5`	`#79b8ff`
`syntax-constant`	`#005cc5`	`#79b8ff`
`syntax-function`	`#6f42c1`	`#b392f0`
`syntax-keyword`	`#d73a49`	`#f97583`

Charts

Token	Light	Dark
`chart-1`	`blue-600`#3b5cf6	`blue-500`#7698fd
`chart-2`	`green-800`#198b43	`green-500`#6bd586
`chart-3`	`yellow-800`#cb9f34	`yellow-500`#f2cf76
`chart-4`	`red-800`#b82d35	`red-500`#f17471
`chart-5`	`grey-600`#808080	`grey-500`#aeaeae

Sidebar

Token	Light	Dark
`sidebar`	`grey-100`#fafafa	`grey-1200`#080808
`sidebar-foreground`	`grey-1100`#161616	`grey-100`#fafafa
`sidebar-primary`	`grey-1000`#242424	`grey-700`#5c5c5c
`sidebar-primary-foreground`	`grey-50`#fff	`grey-50`#fff
`sidebar-accent`	`#0000000a`	`#ffffff0f`
`sidebar-accent-foreground`	`grey-1100`#161616	`grey-100`#fafafa
`sidebar-border`	`#0000001a`	`#ffffff1a`
`sidebar-ring`	`blue-500`#7698fd	`blue-500`#7698fd

Palette

These are the same in both modes. Each step is a variable, such as --palette-blue-600.

Step	grey	red	orange	yellow	green	cyan	blue	purple	pink
50	#fff
100	#fafafa	#fceceb	#fdf2ed	#fefaec	#e7f9ea	#e2f7fb	#ecf1fe	#ebecfe	#fdecf3
200	#f2f2f2	#f6d5d3	#ffe7dc	#fcefd0	#d0f0d5	#c4edf4	#d7e2fc	#d5d5fc	#f7d5e4
300	#eee	#f2bbb7	#ffd8c6	#f7e5b5	#b8e9c1	#a3e4ef	#c3d4fd	#b9b8f5	#fabcd8
400	#dbdbdb	#f29b96	#ffc1a4	#f3da9b	#96e3a6	#65d9eb	#a2bcff	#9e99f7	#f799c6
500	#aeaeae	#f17471	#ffa478	#f2cf76	#6bd586	#00c5df	#7698fd	#8271f8	#f26cb2
600	#808080	#f1484f	#ff8648	#f6c251	#49c970	#00abcf	#3b5cf6	#7152f4	#f64aab
700	#5c5c5c	#d92e3c	#ee7330	#e7af36	#2eaf5a	#0096b8	#3250df	#623be2	#e4429e
800	#3a3a3a	#b82d35	#d16427	#cb9f34	#198b43	#007d9b	#2c47c8	#5230c2	#c83d8b
900	#2e2e2e	#97252b	#b35624	#ac8833	#1d783c	#006c85	#263fa9	#442aa1	#aa3576
1000	#242424	#7a1f23	#954c27	#8e7231	#196130	#005a6e	#22388f	#361f83	#8c2d61
1100	#161616	#5f1a1c	#723d22	#68552b	#164c26	#004756	#1c2e70	#2b1b6a	#6f284f
1200	#080808	#461516	#5a2c14	#4b4025	#14361d	#00353f	#1b2852	#221358	#5c1d3f

Type scale

text-base stays at 16px, so inputs can use text-base md:text-sm to keep iOS from zooming in.

Class	Size	Line height
`text-2xs`	11px	16px
`text-xs`	12px	16px
`text-sm`	13px (body)	20px
`text-md`	15px	20px
`text-xl`	21px	28px