Theming and design tokens

​

Turn on dark mode

export function ThemeRoot({ theme, children }: { theme: "light" | "dark"; children: React.ReactNode }) {
  return (
    <div className={theme === "dark" ? "dark" : undefined} style={{ colorScheme: theme }}>
      {children}
    </div>
  );
}

const root = document.documentElement;
root.classList.toggle("dark", theme === "dark");
root.style.colorScheme = theme;

• The dark class is the theme switch. theme.css defines the variant as @variant dark (&:where(.dark, .dark *)) and defines the dark palette in a .dark { ... } block, so both the library’s dark: utilities and its dark token values activate inside that element.
• color-scheme tells the browser to render its own surfaces (scrollbars, native form controls, the canvas behind your page) in the matching scheme. It does not affect any token. Skipping it leaves light scrollbars on a dark page.

​

Theming part of a page

<div className="dark bg-background-primary" style={{ colorScheme: "dark" }}>
  <Card>Rendered with the dark palette</Card>
</div>

​

Design tokens

​

Semantic colour tokens

​

Other token families

​

Typography and icons

​

Matching your app to Fanvue

<main className="min-h-dvh bg-background-primary text-content-primary">
  <header className="border-border-primary border-b bg-surface-primary">
    <h1 className="typography-header-heading-sm">Insights</h1>
  </header>
</main>

​

Overriding tokens

@import "tailwindcss";
@source "../node_modules/@fanvue/ui";
@import "@fanvue/ui/styles/theme.css";

:root {
  --color-brand-primary-default: #00aeef;
}

.dark {
  --color-brand-primary-default: #38c6f4;
}

​

Do and do not

• Build with semantic tokens and their utilities rather than hex values or primitives.
• Pass className to a component to adjust layout and spacing. Components merge it through tailwind-merge, so your utility beats theirs on a conflict rather than producing two competing classes. The same merge helper is exported as cn for your own components.
• Use the props a component exposes for visual variants. variant, size, and negative cover the supported permutations and are the only ones that stay correct through an upgrade.
• Override tokens globally when your whole app needs a different value, and scope an override to a wrapper class when only one area does.

• Do not target a component’s internal elements with descendant selectors or !important. Internal markup and class names are not a public API and change without a major version.
• Do not style against Radix data-* attributes on internals for anything beyond your own wrapper elements.
• Do not set colours on component children that the component also sets. The result depends on cascade order and breaks the theme in the mode you did not test.
• Do not assume a token is safe to repurpose because its current value suits you. Check what it means first: --color-content-always-white stays white in both themes by design.

​

Next steps