Skip to Content
BBRICKSv0.7.4
Foundations

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 wrapper

Nothing 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:

HookControls
--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-cursorButtons
--field-radius, --field-hForm fields
--modal-w, --modal-pad, --drawer-w, --drawer-dur, --drawer-ease, --dlg-title-fs, --dlg-title-fwModal and drawer (the title's size and weight: 22px / 700 by default, 20px / 800 in the pr theme)
--page-title-fs, --page-sub-maxPage header
--bulk-*The bulk bar
--chipf-padToolbar 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-wListToolbar's search box width: 260px, 248px in the pr theme
--tier-<key>-bg, --tier-<key>-inkA 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:

PropertyControls
--tile-min-hThe minimum height of a Tile size="short" (110px when unset)
--fc-colsFindCreatorCard'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.

On this page