Theme

Color, radius, border width, field height, font and motion go through CSS variables prefixed with --tuc-, and all of them live in :root. Changing the look means overriding variables, with nothing to recompile: no color, radius, border or height value is hard-coded in the components' CSS.

In the swatches, each color also changes --tuc-accent-fg, and --tuc-accent-text too — the accent shade used as text color in the active menu item and in the select's tag. Changing only --tuc-accent would leave unreadable text on the primary button.

:root {
  --tuc-accent: #4f46e5;
  --tuc-accent-hover: #4338ca;
  --tuc-accent-fg: #ffffff;       /* text on top of the accent */
  --tuc-accent-text: #4338ca;     /* accent as text color, in light mode */
  --tuc-radius: 1rem;             /* rounder corners */
  --tuc-control-height: 2.5rem;   /* taller fields */
}
.dark {
  --tuc-accent-text: #818cf8;     /* in dark mode, a lighter shade for contrast */
}

The accent and the text on it

The default accent is neutral: black in light mode and near-white in dark mode. The color belongs to your project — the package doesn't impose a brand, and it fits any brand until you change it. The orange you see in this documentation is the site's color, set the same way you would set yours.

The accent has a separate token for each role, because a bright color rarely works for all of them. On this site's orange, text is white (--tuc-accent-fg), with a contrast of 2.7 — a brand choice; if you need 4.5, use #0a0a0a (7.4). And bright orange as text color on a light background also gives 2.7, so links, the active menu item, the select's tag, "today" in the calendar and active icons read --tuc-accent-text, here #B84300 in light mode (5.5 on white) and #FF7501 itself in dark mode (6.7).

/* This site's orange */
:root {
  --tuc-accent: #FF7501;
  --tuc-accent-hover: #FF8A2A;
  --tuc-accent-fg: #ffffff;
  --tuc-accent-text: #B84300;
  --tuc-thumb: #ffffff;
}
.dark {
  --tuc-accent: #FF7501;
  --tuc-accent-hover: #FF8A2A;
  --tuc-accent-fg: #ffffff;
  --tuc-accent-text: #FF7501;
  --tuc-thumb: #ffffff;
}

.dark repeats the accent because the neutral default changes with the theme: without it, dark mode would go back to near-white.

Semantic tones never read the accent. Success, warning, danger and info have their own tokens, because the brand can be any color and the meaning must not change with it. That's why info got --tuc-info: reading the accent, with orange the info alert looked the same as the warning one, and the "New" badge was indistinguishable from "Under review".

Tokens

The complete list, with the value for each theme. The source of truth is src/styles/core/tokens.css; llms.txt has the same list, generated from the code.

Surface and text

Accent

Semantic tones

Text tone and solid fill are different tokens on purpose. --tuc-danger is lighter in dark mode to have contrast on a dark background — and a button painted with it would look pastel with white text on top. --tuc-danger-fill is the same in both themes.

Shape and size

Depth and motion

Entry and exit use different curves on purpose: using the same curve for both makes the exit feel sluggish.

Dark mode

Dark mode follows the .dark class on <html>, the convention of Tailwind and of Django's modern admin. data-theme="dark" works too.

<html class="dark">
<html data-theme="dark">

To follow the operating system, mark the root with data-tuc-theme="auto". It's opt-in on purpose: following the system by default made the component turn dark on its own in a light page. The project decides the theme, not the operating system.

<html data-tuc-theme="auto">

Dark mode also sets color-scheme: dark, which makes the browser draw scrollbars and native fields in a dark tone — only inside the components, so it doesn't force the color scheme on the whole page.

Scoping by container

Since they are variables, the scope is up to you: in :root they apply to the whole page, and declared on a container they apply only inside it. That's how you get a panel with its own color, or a dark band on a light page.

.panel-green {
  --tuc-accent: #0f766e;
  --tuc-accent-hover: #115e59;
  --tuc-accent-fg: #ffffff;
  --tuc-accent-text: #0f766e;
  --tuc-accent-soft: color-mix(in oklab, var(--tuc-accent) 12%, transparent);
  --tuc-accent-ring: color-mix(in oklab, var(--tuc-accent) 35%, transparent);
}
.dark .panel-green {
  --tuc-accent-text: #2dd4bf;     /* accent text readable on a dark background */
}

/* .dark on a container: the tones change, and their soft background has to be redone there */
.band.dark {
  background: var(--tuc-bg);
  --tuc-success-soft: color-mix(in oklab, var(--tuc-success) 12%, transparent);
  --tuc-warning-soft: color-mix(in oklab, var(--tuc-warning) 14%, transparent);
  --tuc-danger-soft: color-mix(in oklab, var(--tuc-danger) 12%, transparent);
  --tuc-info-soft: color-mix(in oklab, var(--tuc-info) 12%, transparent);
}

A panel that opens outside the container — calendar, select list, menu, toast — is inserted at the end of <body> and doesn't inherit its variables. For those, declare the theme in :root, or use appendTo where the component offers it.

Compact layout

Below 40rem (640px) the layout becomes compact. The same breakpoint applies to the CSS and to the date picker's JavaScript, and it's based on width — not on pointer: coarse —, because a laptop with a touchscreen shouldn't get phone behavior.

If your project switches layout at another breakpoint, the library's compact mode won't follow — it's fixed at 40rem. Your own fields should use the same 16px on phones for the same reason; it's shadcn's text-base md:text-sm pattern.