Theming
Override tokens, the PR theme, wrapper themes and the theme hooks.
Every colour, radius and size is a CSS variable in tokens.css. Re-theme by overriding variables on :root or on a wrapper element. All the names are listed, with their values, on Design tokens.
Override on :root
Load your override after tokens.css:
:root {
--rasp: #2c45a6;
--rasp-d: #1f3280;
--rasp-50: #e4ebff;
}Overrides on :root need nothing else: tokens.css declares its aliases (--color-accent: var(--rasp)) on the same element, so they follow.
The PR theme
The pr theme is a second token file. It sets only names that tokens.css declares (a test checks that), and applies to [data-bricks-theme='pr']:
import '@ergasti/bricks/tokens.css';
import '@ergasti/bricks/themes/pr.css'; // after tokens.css
document.documentElement.dataset.bricksTheme = 'pr'; // or data-bricks-theme="pr" on any wrapperNothing changes without the attribute, so one page can show both looks side by side. The PR mock is drawn on the same palette as the brand mock; the theme pins every palette value anyway, so the PR look stays on its own mock when the brand default moves. What it changes: the 248px sidebar, the 4px input focus halo, and the theme hooks below. Two PR mock values fail WCAG AA and are not taken (--ink-3 and --ok); the AA values of tokens.css stay. src/pr/THEME-GAPS.md in the repository lists what tokens cannot express.
Brand and PR side by side
The default tokens, and the pr theme on a wrapper (data-bricks-theme="pr"): the same components, with the segmented control, ghost button, field radius and page title taking the theme's hooks. A theme can sit on <html> or on any element, so both can share a page.
Code
import { Button, FormField, KpiCard, KpiGrid, Segmented } from '@ergasti/bricks';
function Sample({ title }: { title: string }) {
return (
<div style={{ display: 'grid', gap: 12, padding: 16, background: 'var(--bg)', borderRadius: 18, minWidth: 0 }}>
<b>{title}</b>
<Segmented label="Range" value="30" onChange={() => {}} options={[['7', '7 days'], ['30', '30 days'], ['90', '90 days']]} />
<div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}><Button>Default</Button><Button variant="ink">Ink</Button><Button variant="ghost">Ghost</Button><Button size="sm">Small</Button></div>
<FormField label="Group name" hint="A field uses --field-h and --field-radius."><input defaultValue="Top sellers" /></FormField>
<KpiGrid><KpiCard tone="sky" icon="creators" label="Groups" value="3" sub="Open the Groups tab" /></KpiGrid>
</div>
);
}
function SideBySide() {
return (
<div style={{ display: 'grid', gap: 16, gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))' }}>
<div data-bricks-theme="brand"><Sample title="Brand (default tokens)" /></div>
<div data-bricks-theme="pr"><Sample title='data-bricks-theme="pr"' /></div>
</div>
);
}Theme hooks
Kit and shell rules read a set of variables with the same value as their fallback, so the brand look is unchanged and a theme can change shape without new selectors:
| Hook | Controls |
|---|---|
--seg-* | The segmented control: track, line, selected background, ink and shadow, font size, padding |
--btn-ghost-ink, --btn-ghost-hover, --btn-sm-pad, --disabled-opacity, --disabled-cursor | Buttons |
--field-radius, --field-h | Form fields |
--modal-w, --modal-pad, --drawer-w, --drawer-dur, --drawer-ease, --dlg-title-fs, --dlg-title-fw | Modal and drawer (the title's size and weight: 22px / 700 by default, 20px / 800 in the pr theme) |
--page-title-fs, --page-sub-max | Page header |
--bulk-* | The bulk bar |
--chipf-pad | Toolbar filter chips |
--shell-* | The shell's sidebar colours, nav rows, page title and main column padding, the header search pill's width (--shell-search-w, and --shell-search-w-narrow at 1240px and under) |
--lt-search-w | ListToolbar's search box width: 260px, 248px in the pr theme |
--tier-<key>-bg, --tier-<key>-ink | A tier chip's colours (TierChip, TierBadge) when the provider's tiers give none |
A few components also read a custom property that is not declared in tokens.css, so it has no value until you set one on the component or a parent:
| Property | Controls |
|---|---|
--tile-min-h | The minimum height of a Tile size="short" (110px when unset) |
--fc-cols | FindCreatorCard's stat row columns, e.g. 1.35fr 1fr 1fr (one column per stat when unset) |
The values for brand and PR are in the hooks table on Design tokens.
Wrapper themes: set the aliases too
An alias is resolved where it is declared. tokens.css declares --color-accent: var(--rasp) on :root, so a wrapper that only changes --rasp still inherits the :root accent, and everything that reads --color-accent keeps the old colour. A wrapper theme that changes a palette variable must also set the hooks that alias it (--color-accent, --btn-ghost-ink, --bulk-line, --shell-side-bg, …) in the same block, and one that changes --shell-search-w sets --shell-search-w-narrow too, as themes/pr.css does for itself. This is the 0.2.0 note from the migration guide, and the example below shows it.
Override variables on a wrapper
Changing --rasp on a wrapper is not enough on its own: --color-accent is declared on :root as var(--rasp), and a custom property's var() is resolved where it is declared, so a wrapper must also set the aliases (--color-accent and the --btn-ghost-* hooks) the same way themes/pr.css does. Left: only --rasp set. Right: --rasp and its aliases set.
Code
import type { CSSProperties } from 'react';
import { Button, ListToolbar } from '@ergasti/bricks';
const retheme = (extra: Record<string, string>): CSSProperties => ({ ['--rasp' as string]: '#2C45A6', ['--rasp-d' as string]: '#1F3280', ['--rasp-50' as string]: '#E4EBFF', ...extra } as CSSProperties);
function Override() {
const alias = { ['--color-accent' as string]: 'var(--rasp)', ['--color-accent-dark' as string]: 'var(--rasp-d)', ['--color-accent-light' as string]: 'var(--rasp-50)', ['--btn-ghost-ink' as string]: 'var(--rasp-d)', ['--btn-ghost-hover' as string]: 'var(--rasp-50)', ['--focus-ring' as string]: '0 0 0 5px var(--rasp-50)' };
return (
<div style={{ display: 'grid', gap: 16, gridTemplateColumns: 'repeat(auto-fit, minmax(280px, 1fr))' }}>
<div style={retheme({})}>
<p className="kit-muted">Only --rasp</p>
<div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}><Button variant="rasp">Rasp button</Button><Button variant="ghost">Ghost</Button></div>
<ListToolbar chips={{ label: 'Status', value: 'all', onChange: () => {}, options: [{ value: 'all', label: 'All' }, { value: 'live', label: 'Live' }] }} />
</div>
<div style={retheme(alias)}>
<p className="kit-muted">--rasp plus its aliases</p>
<div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}><Button variant="rasp">Rasp button</Button><Button variant="ghost">Ghost</Button></div>
<ListToolbar chips={{ label: 'Status', value: 'all', onChange: () => {}, options: [{ value: 'all', label: 'All' }, { value: 'live', label: 'Live' }] }} />
</div>
</div>
);
}Dark mode
There is none. The library ships a light palette and no dark scheme; these docs add a dark chrome around examples, and the examples always draw on the library's own light surface. An app that needs a dark theme would write one as a token file, the way themes/pr.css is written, and set the aliases as above.