Theming

How the theme works

Your stylesheet holds the whole theme. init from the suiss/ui CLI writes it to app/globals.css (Next.js) or src/index.css (Vite), and projects that use the registry CLI already have one. It has four parts:

• Color values under :root (light) and .dark (dark).
• The base --radius.
• The font, set as --font-sans.
• An @theme inline block that maps each value to a Tailwind name, such as --color-background: var(--background);.

It imports tw-animate-css for the enter and exit animations, and shadcn/tailwind.css for the shared variants (data-open, data-checked and the like), the accordion keyframes and the no-scrollbar, scroll-fade-* and shimmer utilities. Text sizes, shadows and spacing are the Tailwind defaults.

The variable names are the common theme variables used across Tailwind component libraries, so a theme written for one of them works here, and ours works there. The values are our own: a white and true-black canvas, gray text in the system style and a blue primary color.

@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";
@import "@fontsource-variable/inter";

@custom-variant dark (&:is(.dark *));

:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.2316 0.0038 286.09);
  --primary: oklch(0.5629 0.1933 256.16);
  --primary-foreground: oklch(1 0 0);
}

.dark {
  --background: oklch(0 0 0);
  --foreground: oklch(0.9707 0.0026 286.29);
  --primary: oklch(0.669 0.1808 251.84);
  --primary-foreground: oklch(1 0 0);
}

@theme inline {
  --font-sans: -apple-system, BlinkMacSystemFont, "Inter Variable", sans-serif;
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

The theme item

Adding components with the registry CLI keeps the colors your project already has. To use the suiss/ui values instead, add the theme item:

$ pnpm dlx shadcn@latest add @esuiss/theme-suiss

The theme item is the same for every style and primitive base. It writes every light and dark value under :root and .dark, including --radius, the chart colors and the sidebar colors, and adds the radius scale and the font stack to @theme inline. It also installs @fontsource-variable/inter and imports it from your stylesheet. Projects set up with npx @esuiss/ui init already have all of it.

Using variables

Every color becomes a Tailwind color. Use it with any color utility.

<div className="rounded-lg border border-border bg-muted p-4">
  <p className="text-foreground">Title</p>
  <p className="text-muted-foreground">Supporting text</p>
</div>

Colors come in pairs: a background and the text that sits on it. For example, bg-primary takes text-primary-foreground, and bg-card takes text-card-foreground. A variable without the -foreground suffix is the background; the one with it is the text.

Interaction states

There is no separate variable per state. States use the same variables with an opacity, and disabled elements are dimmed:

The button component uses them this way:

"bg-primary text-primary-foreground hover:bg-primary/80 disabled:opacity-50"

Variables

Values are from the default stylesheet.

Base

Primary and secondary

Muted and accent

Destructive, borders and focus

Charts

Series colors. Charts reference them as var(--chart-1) to var(--chart-5) in their config.

Sidebar

The sidebar component has its own set, so it can differ from the page.

Status and other colors

Success, warning and decorative colors use the Tailwind palette directly, with a lighter shade in dark mode for text, for example text-green-600 dark:text-green-400 and bg-green-500/10. The dimmed layer behind dialogs, sheets and drawers is bg-black/50.

Mobile

React Native, SwiftUI and Compose use the same variables with the same light and dark values, generated from one token file.

Pressed elements fade to 80% opacity and disabled elements to 50%, on every platform.

Text sizes and shadows are the Tailwind defaults on every platform: xs is 12 points on a 16-point line, up to 3xl at 30 on 36, and shadow-md and shadow-lg keep both of their layers. SwiftUI and Compose name 2xl and 3xl as xl2 and xl3.

Focused fields in Uniwind and NativeWind draw the same border-ring ring-3 ring-ring/50 ring as the web. SwiftUI and Compose keep the system focus.

Radius

--radius is 0.625rem by default. Every rounded component scales from it.

Customize

• Change a color. Edit its value under :root (light) and .dark (dark).
• Use another theme. Themes written with the same variable names drop in: replace the :root and .dark blocks with theirs and keep the @theme inline block.
• Add a color. Define it under :root and .dark, then map it in @theme inline, for example --color-brand: var(--brand);. Classes such as bg-brand and text-brand become available.
• Change the font. Set --font-sans in @theme inline.
• Change the corner radius. Set --radius under :root.

Dark mode

Dark mode is enabled by the dark class on <html>. Every token switches with it.

For a theme switch, add the theme component. It is not added by add --all, so projects that stay in one appearance never get it.

$ pnpm dlx shadcn@latest add @esuiss/theme

Or with the suiss/ui CLI:

$ pnpm dlx @esuiss/ui add theme

It gives you ThemeProvider, useTheme, ThemeToggle and ThemeScript. Adding it also appends the keyframes for the animated theme switch to your stylesheet. The provider remembers the choice (light, dark or system) and follows the system setting when it is system. ThemeScript sets the class before the page paints, so there is no flash of the wrong theme.

import { ThemeProvider, ThemeScript } from "@/components/ui/theme"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}

With Vite, wrap your app in ThemeProvider and put the same script in index.html, before your app script:

<script>
  (()=>{try{var t=localStorage.getItem("theme")||"system";var d=t==="dark"||(t==="system"&&matchMedia("(prefers-color-scheme: dark)").matches);var r=document.documentElement;r.classList.toggle("dark",d);r.style.colorScheme=d?"dark":"light"}catch(e){}})()
</script>

ThemeToggle switches with an animated reveal built on the View Transitions API. Choose the effect (circle, rectangle, polygon or circle-blur), where it starts with origin, and add blur for a softer edge.

<ThemeToggle effect="circle" origin="top-right" />
<ThemeToggle effect="rectangle" origin="bottom-up" blur />

To build your own control, use setTheme from useTheme. Pass a transition as the second argument to animate it, or leave it out to switch instantly. Browsers without View Transitions, and visitors who prefer reduced motion, switch instantly either way.

const { theme, setTheme } = useTheme()
setTheme("system", { effect: "circle", origin: "top-center" })