Customization

Cirth is CSS first. Every colour, space, radius, shadow and font is a --cirth-* custom property, and the supported way to change one is a rule in your own stylesheet, loaded after Cirth. No Sass, no build step, no rebuild.

<link rel="stylesheet" href="dist/cirth.min.css">
<link rel="stylesheet" href="your-theme.css">

/* your-theme.css */
:root {
  --cirth-primary: #2563eb;
}

That one line is a worked example rather than a teaser: it moves the accent everywhere it is used — links, focus rings, the filled button, its hover, the underline tint, the checkbox mark, the switch, the range thumb — because those are derived from it rather than listed alongside it. The next section is about why, because it is the thing that makes the rest of this page short.

How the token system works #

Cirth's tokens are not one flat list. There are five kinds, and knowing which one you are looking at tells you what will happen when you set it.

Inputs #

A small set of tokens that other tokens are built from. --cirth-primary is the clearest one, and the status trio — --cirth-error, --cirth-success, --cirth-warning — behaves the same way. Setting an input is the cheapest possible change: everything downstream follows.

:root {
  --cirth-error: #b91c1c;
}

That moves the invalid field border, the border it takes while you are typing in it, the <del> ink, the low reading on a <meter>, and the tint a status surface would sit on. You do not have to know which of those exists to retune them together.

Derived tokens #

Tokens computed from an input, at runtime, by the browser. They are written as relationships:

--cirth-primary-active: color-mix(in oklch, var(--cirth-primary) 83.5%, black);
--cirth-primary-underline: oklch(from var(--cirth-primary) l c h / 50%);

You can set a derived token directly, and sometimes you should — that is how you break a relationship on purpose. The playroom preset does exactly this so its buttons brighten on hover instead of darkening, which no proportional darkening could produce. What you should know is that doing so opts that token out permanently: it stops following the input, and a later change to the accent will leave it behind.

Slots #

A handful of names are not theme settings at all. They are the variables a component paints through, and components rebind them constantly:

--cirth-background-color · --cirth-color · --cirth-border-color · --cirth-box-shadow · --cirth-underline · --cirth-font-size · --cirth-font-weight · --cirth-line-height · --cirth-letter-spacing · --cirth-text-decoration

--cirth-color is declared on the page, and then again on every heading, on a button, inside a dropdown, on a form field — each time pointing at the token that element should use. Setting it at :root changes the page default and nothing else, because everything else was already given its own value.

That is worth stating plainly because it is the one place where an override can look like it silently did nothing:

:root {
  --cirth-color: rebeccapurple;   /* body text turns purple */
}
/* headings do not: they are given --cirth-h1-color and friends */

If you want the headings too, set the tokens the headings actually read (--cirth-h1-color … --cirth-h6-color). The reference at the end of this page marks every token with its kind, so you can tell at a glance whether you are setting a value or a slot.

When you need to refer to the page itself, use the two page roles. They are values, not slots, and no component is allowed to shadow either of them:

• --cirth-canvas — the page surface. Use it for an opaque background on a control, or a tint mixing toward the page. --cirth-background-color defaults to it.
• --cirth-ink — the page text colour. Use it wherever you need the ink the document is set in rather than the ink of whatever you happen to be inside. --cirth-color defaults to it.

The distinction matters most inside a <button>, a link, an <input> or a heading, because each of those rebinds --cirth-color for its own subtree. A custom control built on <button> — a tab, a toolbar, a chip — that reaches for --cirth-color gets the button's on-surface ink, which on a button that has dropped its fill is white on white. Reach for --cirth-ink instead and you get the page's ink, whatever the theme is.

--cirth-contrast-text is not the same thing: that is maximum-contrast ink, the role the .contrast variant is built on, not the ink of body text.

Roles #

Standalone semantic settings that a component reads directly. A role does not promise to drive a family of other tokens: --cirth-modal-max-width, --cirth-code-color, and --cirth-form-element-border-color each configure one responsibility. Set one when that responsibility is exactly what you want to change.

Scales #

The raw ladders: --cirth-space-*, --cirth-radius-*, --cirth-font-size-*, --cirth-border-width-*, --cirth-duration-*. Every step exists whether or not the library uses it, so picking one is the same exercise wherever you are. You will usually reach for the role token that sits on top of a scale — --cirth-spacing rather than --cirth-space-5 — but the steps are there when you want to move one component without moving the rest.

Start here #

Four tokens carry most of a retheme. If you change nothing else, change these.

The plain preset is those first two plus three role choices, and nothing else — see Colors for what it looks like. It exists partly to prove the point: a coherent, accessible, light-and-dark theme in five declarations.

Here is a custom accent applied live, which is two declarations — the pair and a radius — over the build this page is already using:

<style>
  /* Two declarations, because the accent is an input: the fill, the hover,
     the focus ring and the underline tint all derive from --cirth-primary.
     The pair covers both schemes at once — light-dark() is resolved where
     the token is used, so this holds inside a forced-scheme subtree too.
     The light half is darker than a naive rose (#e11d48 measures 4.36:1 on
     the page surface, below AA) because it has to read as text, not only
     as a fill. */
  .demo-brand {
    --cirth-primary: light-dark(#c81e42, #fb7185);
    --cirth-border-radius: 9999px;
  }
</style>
<div class="demo-brand">
  <button type="button">Custom primary</button>
  <button type="button" class="outline">Outline</button>
  <button type="button" class="ghost">Ghost</button>
  <p><a href="#">A link picks up the same override.</a></p>
</div>

Colour #

The accent #

--cirth-primary is the input. These follow it, and you do not normally set them:

--cirth-primary-on-surface is the one to check when you pick an unusual accent. It is white by default, which is right for most accents and wrong for a light one — a pale yellow accent with white text on it is unreadable. It is a plain value rather than a derivation because choosing between light and dark text is a decision, not a mix. A relative-color threshold was tested across 936 accents: 10 results missed 4.5:1 and it chose the worse of black and white in 14 cases, concentrated around cyan–teal. The exact contrast-color() decision is outside Cirth's browser floor, so the role remains explicit until the platform can choose reliably. A future theme generator can make the same choice before it emits a theme.

:root {
  --cirth-primary: #fbbf24;          /* a light amber */
  --cirth-primary-on-surface: #1c1917;  /* so the label stays readable */
}

The name now says the role before it says the state: text, surface, border, underline, focus, and on-surface, with -active appended where a state needs another value. That is the same vocabulary the status families use below, rather than the former mix of background, hover and inverse.

--cirth-secondary-text and --cirth-contrast-text anchor the other two colour groups, with the same shape. They are roles rather than inputs: the default theme chooses their neutral and maximum-contrast values directly. .secondary and .contrast on a button or link swap which group it reads from; .outline and .ghost keep the group and drop the fill. See Button.

Status colours #

Three inputs, each driving four roles:

--cirth-success and --cirth-warning are identical in shape. A <mark> does not imply warning: its background is derived from --cirth-primary, so highlighted evidence follows the chosen accent while status content stays on the explicit *-surface families.

Status hues are deliberately not fixed constants. If your brand overlaps a conventional status hue, move the status family rather than avoiding the brand — what has to stay true is that the two remain distinguishable, and that state is never signalled by colour alone (WCAG 1.4.1). Cirth's own validity styling pairs colour with an icon for that reason.

Surfaces #

--cirth-canvas and --cirth-ink are the two inputs in this family — the page's surface and the page's ink. Set either and the tokens that alias it follow: --cirth-background-color and the surface ladder from the canvas, --cirth-color and the component inks (accordion summary, dropdown, popover, the <kbd> fill) from the ink. The others are runtime relationships: code is the deepest recess, the resting field sits between it and the canvas, the band and card add lightness, and a focused field rises to the canvas. Dropdown and popover alias the card because they are floating sheets. Overriding any derived token directly still breaks its relationship on purpose.

The ladder preserves the canvas hue and chroma, so warm paper stays warm, Plain becomes neutral, and Playroom carries its violet temperature without restating a parallel scale. Both schemes now tell the same semantic story:

light: code 95.5 < control 96.6 < canvas 97.4 < band 98.3 < card 99.2
dark:  code 18.2 < control 19.4 < canvas 20.2 < band 22.7 < card 24.2

A single --cirth-canvas override therefore moves card, form, code, dropdown, and popover in light, dark, and forced-theme subtrees. Plain uses that one surface input; it does not enumerate the ladder.

Light and dark #

Cirth ships both schemes. The scheme follows the operating system, and data-theme="light" or data-theme="dark" on any element forces one for that subtree.

<html data-theme="dark">

A :root override applies to both schemes, and it applies everywhere — including inside a subtree that forces one:

:root {
  --cirth-primary: #2563eb;
}

When light and dark should differ, give the token both values at once with light-dark():

:root {
  --cirth-primary: light-dark(#2563eb, #93c5fd);
}

This is the same shape Cirth uses internally. The pair is resolved where the token is used, against the colour scheme in effect at that point, so one line covers the page and any widget that forces its own scheme.

You can still target the scheme selectors directly. They are more specific than a plain :root, which makes them the tool for changing one scheme without touching the other:

:root:not([data-theme="dark"]) {
  --cirth-primary: #2563eb;
}

[data-theme="dark"] {
  --cirth-primary: #93c5fd;
}

For a value that should hold everywhere, prefer the pair: it is one line, and it cannot fall out of step with itself.

data-theme in scoped builds #

The builds differ in where they look for the attribute.

• Unscoped builds respond to data-theme on any ancestor.
• Scoped builds only look at the .cirth element itself, or elements inside it. <html data-theme="dark"> around a .cirth widget has no effect, because every generated selector is anchored to the wrapper.

If you embed a scoped widget in a host page that manages its own dark mode, mirror the host's choice onto the wrapper:

<div class="cirth" data-theme="dark">…</div>

Increased contrast #

Cirth carries a prefers-contrast: more pass that strengthens inks, hairlines and focus rings. Your overrides load after it, so a token you set unconditionally will win there too — which usually means the preference stops working for that token.

/* your accent, in both modes */
:root {
  --cirth-primary: #2563eb;
}

/* and a stronger one where the user asked for it */
@media (prefers-contrast: more) {
  :root {
    --cirth-primary: #1e3a8a;
  }
}

Both presets do this, and it is worth copying if you set colours at all.

Typography #

:root {
  --cirth-font-family: Inter, system-ui, sans-serif;
  --cirth-font-family-display: Inter, system-ui, sans-serif;
}

--cirth-font-family is body text and every control that inherits it. --cirth-font-family-display is headings — it points at the serif stack by default, which is part of Cirth's own identity; setting it to var(--cirth-font-family) is how both presets make headings match the body.

Cirth loads no webfonts. If you want one, load it yourself and point the token at it afterwards:

<link rel="stylesheet" href="https://your-cdn.example/inter.css">
<link rel="stylesheet" href="your-theme.css">

The scale runs --cirth-font-size-xs through -7xl. h4–h6 read steps from it directly; h1–h3 are fluid and read their clamp bounds from it, so moving a step still moves the heading:

:root {
  --cirth-font-size-6xl: 2.25rem;   /* h1 stops growing sooner */
}

The shipped ladder is 44 / 32 / 24 / 20 / 18 / 16 at the default root size. If you want display type beyond that, ask for it on the element rather than moving the scale everyone else reads:

/* a campaign page, opting in through the slot every heading resolves
   through — no second API, and the rest of the site keeps product scale */
.hero h1 {
  --cirth-font-size: clamp(2.75rem, 2rem + 1.9vw, 3.5rem);
}

--cirth-line-height, --cirth-font-weight and --cirth-letter-spacing are slots: set at the root they change the page default, and elements that were given their own value keep it. The two tracking steps have consumers — --cirth-letter-spacing-tight on h1/h2, --cirth-letter-spacing-snug on h3/h4 — so overriding one moves the headings that read it. --cirth-form-label-font-weight is separate so labels can be heavier than the prose around them.

Spacing and layout #

--cirth-spacing is the flow knob: it times the space between things and the padding of the document blocks that are made of running text. Set it at the root, which is where the tokens that derive from it are declared:

:root {
  --cirth-spacing: 0.75rem;   /* a denser interface */
}

What follows the knob #

Nothing else has to be restated to move with it. A few document blocks read --cirth-spacing directly for the same reason: <pre>, <blockquote> and table cells are running text with a box around it, so their padding is part of the same rhythm.

What deliberately does not #

To change control or card density, set those tokens. They are public, they are documented in the reference below, and overriding one of them is not a workaround — it is the second half of the same contract.

A note on control height: Cirth's controls are at least 44px tall — WCAG 2.5.5's target size. Button, input, select and one-line textarea share one runtime formula made from --cirth-font-size-md, line-height, vertical padding and border. Text inputs use that result as their fixed one-line height; controls that may legitimately grow use it as a floor. Changing the padding therefore changes their internal proportions without letting an equivalent control fall out of alignment. Navigation opts down to a 40px band — comfortably clear of WCAG 2.5.8's 24px AA minimum — because a nav row is compact by design and a header should not have to fight the framework for a height.

Borders, radii and outlines #

:root {
  --cirth-border-radius: 0;        /* square corners everywhere */
}

--cirth-border-radius is the single knob. The per-component radii are derived from it — a card is softer, a checkbox and inline code are capped so they never read as circles — so zeroing it zeroes them too.

--cirth-border-width and --cirth-outline-width read steps from one stroke ladder, --cirth-border-width-*.

Motion #

:root {
  --cirth-transition: 120ms ease-out;
}

One token covers every transition in the library. It is composed from --cirth-duration-* and --cirth-ease-*, which are there if you want a different pairing per component.

Cirth already honours prefers-reduced-motion, with one deliberate exception: a busy indicator keeps moving, because a spinner that has stopped says the opposite of what it means.

Worked examples #

Rebrand the accent #

Everything the accent touches, in one line per scheme:

:root {
  --cirth-primary: light-dark(#7c3aed, #a78bfa);
}

@media (prefers-contrast: more) {
  :root {
    --cirth-primary: light-dark(#5b21b6, #c4b5fd);
  }
}

Check --cirth-primary-on-surface if your accent is light: the label on a filled button has to clear 4.5:1 against it.

Swap the typography #

:root {
  --cirth-font-family: "IBM Plex Sans", system-ui, sans-serif;
  --cirth-font-family-display: "IBM Plex Serif", Georgia, serif;
  --cirth-line-height: 1.6;
}

Make it denser #

:root {
  --cirth-spacing: 0.75rem;
  --cirth-border-radius: 0.25rem;
  --cirth-transition: 100ms ease-out;
}

That tightens the flow — prose, sections, grid gaps — and leaves controls and cards where they were. Add the control pair if you want the components to come in too:

:root {
  --cirth-form-element-spacing-vertical: 0.375rem;
  --cirth-form-element-spacing-horizontal: 0.75rem;
}

Controls keep their 44px floor either way: the padding shrinks, the target does not.

Change the dark scheme only #

[data-theme="dark"] {
  --cirth-canvas: #0b1120;
  --cirth-card-background-color: #111827;
}

Or, as a pair, if you are setting the light value anyway:

:root {
  --cirth-canvas: light-dark(#ffffff, #0b1120);
}

Theme one embedded widget #

Scoped builds put everything under .cirth, so a widget can carry a theme the host page knows nothing about:

<link rel="stylesheet" href="dist/cirth.scoped.min.css">

<div class="cirth" data-theme="dark" style="--cirth-primary: #34d399">
  <article>
    <h2>Settings</h2>
    <button type="button">Save</button>
  </article>
</div>

Verifying your theme #

Cirth's shipped themes — the default and both presets — are verified: every text pair clears WCAG AA (4.5:1, or 7:1 under prefers-contrast: more) and every non-text indicator clears 3:1, checked in light and dark on every page of this site.

That verification covers the values Cirth ships. It does not extend to values you set. The relationships hold — a derived hover stays proportionally darker than whatever accent you give it — but whether the result clears a threshold depends on the colour you chose. When you change an input, the pairs worth checking are:

• your accent against the page, as link text;
• --cirth-primary-on-surface against --cirth-primary-surface, as a button label;
• --cirth-muted-color against the page;
• the status borders against a field.

What you cannot change with a variable #

Some choices are Sass switches decided when the CSS was compiled, because they change which selectors exist at all:

• Class-based selectors (.container, .grid, .secondary, .outline, .ghost, …) exist in the default build and not in the classless one.
• Scoping every selector under .cirth is the scoped build.
• The .row breakpoint is fixed in src/_breakpoints.scss.

If you need different values for these you are choosing a different published build, not overriding a variable. See Get Started.

Token reference #

Every --cirth-* token Cirth declares, grouped by what it affects. The kind column is the distinction from How the token system works:

• input — set this; other tokens follow
• derived — computed from an input; set it only to break that
• slot — a variable components paint through, not a theme setting
• role — a named setting a component reads directly
• scale — a step on a ladder

Accent and status #

Surfaces and text #

Typography #

Spacing and layout #

Borders, radii and outlines #

Motion, depth and layering #

Form controls #

Components #

Everything else #