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
:root {
--sx-color-accent: oklch(0.4293 0.2006 267.96);
}:root {
--primary: var(--sx-color-accent);
}@theme inline {
--color-primary: var(--primary);
}- Tokens.
tokens.cssholds the raw Statix values as--sx-*variables.pnpm tokensgenerates it from the Penpot export. Nobody edits it by hand. - Semantic variables.
theme.cssmaps 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-softand the--tone-*fills. - Utilities. The
@theme inlineblock turns each semantic variable into Tailwind utilities.--color-primarygives youbg-primary,text-primary,border-primaryand 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.
@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-sansand--font-mono
: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.
[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:
- Designers add a Penpot theme called
darkon top of thestatixset. pnpm tokenswrites one file per Penpot theme. Thedarktheme becomestokens.dark.csswith a.darkselector.theme.cssimports it and the package exports it.- Apps add
mode-watcherand render<ModeWatcher />in the root layout. It sets the.darkclass from the system setting or a toggle.
<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.