Skip to content
Statix Design System

Getting started

Theming

The theme has three layers: raw tokens from Penpot, semantic variables with shadcn names, and the Tailwind utilities built on them. Apps customise the middle layer.

Three layers

1 Tokens tokens.css
:root {
	--sx-color-accent: oklch(0.4293 0.2006 267.96);
}
2 Semantic variables theme.css
:root {
	--primary: var(--sx-color-accent);
}
3 Tailwind utilities theme.css
@theme inline {
	--color-primary: var(--primary);
}
  1. Tokens. tokens.css holds the raw Statix values as --sx-* variables. pnpm tokens generates it from the Penpot export. Nobody edits it by hand.
  2. Semantic variables. theme.css maps the tokens onto the names shadcn components expect: --background, --primary, --border, --muted-foreground. Statix adds a few of its own, such as --ink-2, --primary-soft and the --tone-* fills.
  3. Utilities. The @theme inline block turns each semantic variable into Tailwind utilities. --color-primary gives you bg-primary, text-primary, border-primary and the rest.

Components only use layer 3. Change a semantic variable and every component that uses its utility follows. The colour table lists every mapping.

Primary and accent

shadcn uses two names that are easy to mix up. In Statix, primary is the brand blue and marks the one main action on a screen. accent is shadcn's quiet hover fill for menu items and list rows. It maps to bg-2, a light grey. If you want blue, you want primary.

Override variables

To change the look of an app, override semantic variables after the theme import. Your :root block comes later in the cascade, so it wins.

src/app.css
@import 'tailwindcss';
@import '@statix/ui/theme.css';

:root {
	--primary: oklch(0.45 0.13 160);
	--primary-hover: oklch(0.4 0.12 160);
	--ring: oklch(0.45 0.13 160);
	--radius-card: 20px;
}

Prefer semantic variables over --sx-* tokens. They describe a role, and the token names may change when the Penpot file changes. Keep the pairs together: if you change --primary, check --primary-hover, --primary-foreground and --ring too.

The non-colour variables work the same way:

  • --radius (16px) and --radius-card (28px)
  • --shadow-card, --shadow-overlay, --shadow-dock
  • --font-sans and --font-mono
src/app.css
:root {
	--font-sans: 'Inter Variable', ui-sans-serif, system-ui, sans-serif;
}

A second brand

To restyle one part of a page, scope the overrides to an attribute. Everything inside the element picks up the new values.

src/app.css
[data-brand='agency'] {
	--primary: oklch(0.36 0.08 312);
	--primary-hover: oklch(0.31 0.08 312);
	--primary-soft: oklch(0.94 0.03 312);
	--primary-soft-foreground: oklch(0.3 0.07 312);
	--ring: oklch(0.36 0.08 312);
}
<section data-brand="agency">
	<Button>Invite client</Button>
</section>

Inside a scope, override the semantic variables, not the --sx-* tokens. The semantic variables resolve their var(--sx-*) references on :root, .dark and elements with a data-theme attribute. A token override on any other element never reaches them.

Dark mode

Dark mode is wired but not designed. theme.css defines the dark: variant for elements inside .dark, and mode-watcher is a dependency of the package. There are no dark tokens yet, so the components look the same in both modes. Don't add dark: classes until then.

When the design exists, it arrives without code changes in the components:

  1. Designers add a Penpot theme called dark on top of the statix set.
  2. pnpm tokens writes one file per Penpot theme. The dark theme becomes tokens.dark.css with a .dark selector.
  3. theme.css imports it and the package exports it.
  4. Apps add mode-watcher and render <ModeWatcher /> in the root layout. It sets the .dark class from the system setting or a toggle.
src/routes/+layout.svelte
<script lang="ts">
	import { ModeWatcher } from 'mode-watcher';
	import '../app.css';

	let { children } = $props();
</script>

<ModeWatcher />
{@render children()}

Any other Penpot theme name, for example agency, becomes tokens.agency.css with a [data-theme='agency'] selector. That is the token-based route to a second brand.