Skip to content
Kimenpre-v1documentation home
Color scheme

Themes & color schemes

Every visual value in Kimen resolves from a design token — zero hardcoded values, enforced by lint. A theme is nothing but a set of token assignments, so re-theming is a stylesheet plus one attribute, with no component changes and no runtime code.

Tokens are layered (the Design tokens guide covers each layer in depth):

  1. Primitive — raw ramps (--ki-color-brand-500, --ki-space-md). Never consumed by components directly.
  2. Semantic — meaning, not appearance (--ki-surface-s0…s5, --ki-text-high-em, --ki-outline-low-em). This is the layer a brand reassigns to re-theme everything.
  3. Component — the public styling contract of each element (--ki-button-primary-neutral-rest-bg, --ki-button-md-height). Each component page lists its own under CSS custom properties.

Onmars is the default theme — it is tokens.css itself, no attribute needed. Material 3 ships as the reference second theme and proves in CI, on every commit, that reassigning the token layers alone restyles every component:

<link rel="stylesheet" href="@kimen/tokens/css" />
<!-- opt-in second theme -->
<link rel="stylesheet" href="@kimen/tokens/css/material3" />
<html data-ki-theme="material3">

An unknown data-ki-theme value simply matches no selector: the document stays on the default theme.

Paper ivory and warm charcoal set the light and dark canvases. Ink anchors the primary fill, terracotta marks links, focus and selection, and crimson signals errors. Cards and controls use flat surfaces with hairline edges.

The UI and body stack starts with Instrument Sans. The display and serif stacks start with Newsreader. Each stack includes system fallbacks.

Both themes follow the OS by default and can be forced either way, on the document root or on any element:

<html data-ki-color-scheme="dark"> <!-- force dark -->
<html data-ki-color-scheme="light"> <!-- force light -->
<!-- no attribute: follows the system color scheme -->

This site’s theme toggle drives exactly this attribute, so every live demo on these pages follows it.

The scheme is one declaration, and the token stylesheet makes it: it sets color-scheme: light dark on the root, and data-ki-color-scheme pins it to one side. Every scheme-dependent token is a single light-dark() value that resolves from that declaration, so the tokens and the browser — page canvas, scrollbars, native controls, autofill — always agree. A page that loads only @kimen/tokens/css is coherent in both schemes.

The root declaration is a default with zero specificity. If your page is deliberately single-scheme and already says so in its own CSS (html { color-scheme: light }, before or after the token stylesheet), your declaration wins and the tokens follow it. It has to be CSS: a <meta name="color-scheme"> alone does not pin the page.

Tokens are custom properties: loading them paints nothing. The opt-in page contract paints the page from them — background from --ki-surface-base, text from --ki-text-high-em, and the body family:

<link rel="stylesheet" href="@kimen/tokens/css" />
<link rel="stylesheet" href="@kimen/tokens/css/base" />

It publishes no tokens of its own — it only consumes them, so it never widens the token surface — and it declares no color scheme: the token stylesheet owns that.

Skipping it is supported in both schemes. Without it the page keeps the browser’s own canvas and text color for the active scheme, and every component stays legible on it. That is measured rather than assumed: on a page loading only the token stylesheet, with the visitor’s OS set to dark, all 29 components hold 4.5:1 for every rendered string.

Both themes answer two accessibility preferences of the person, in both schemes, through tokens alone:

  • More contrast (prefers-contrast: more): neutral text — body, secondary, labels, helper and placeholders — measures 7:1 or more against the surface behind it, neutral control boundaries 4.5:1, separators and container edges 3:1, and the keyboard focus ring is 3px thick. Text on brand and tone fills keeps 4.5:1, and disabled controls keep their standard look, so they never read as operable.
  • Less transparency (prefers-reduced-transparency: reduce): every surface that holds content — menus, tooltips, dialogs, glass buttons, badges, alerts — becomes the opaque surface it reads as over the page, and nothing blurs what is behind it. Hover and press washes and the modal backdrop keep their translucency. More contrast implies it: a contrast ratio over glass depends on what is behind the glass.

A page can switch either mode on without the system preference, for an in-app accessibility setting or for browsers that do not report it (Safari has no prefers-reduced-transparency):

<html data-ki-contrast="more">
<html data-ki-transparency="reduce">

A declaration only ever adds: no value switches a mode off against the person’s preference. It takes effect on the document root and on a theme root (an element with data-ki-theme), and a theme root nested inside one that declares it follows it. A region that needs its own contrast declares it next to its theme: <section data-ki-theme="material3" data-ki-contrast="more">.

To give your own theme different values under a mode, restate them under the same media query (and the declaration, if you use it):

@media (prefers-contrast: more) {
:root { --ki-outline-control: #000000; }
}

Any element can make its region compact — a data table, a toolbar, a dense settings panel — with one attribute:

<section data-ki-density="compact">…</section>
<div data-ki-density="default">…</div> <!-- back to the default inside it -->
<html data-ki-density="compact"> <!-- the whole page -->

Compact is Material’s −2 step: controls and rows 8px shorter (40 → 32 in onmars, 48 → 40 for material3 fields) and container padding and gaps ×0.75 (16 → 12). Text, icons, radius, borders, focus rings and content sizes (avatar, badge, QR, progress, video) keep their size, and the size props still pick a size within the density. The nearest declaration wins, theme regions nested inside a compact region stay compact, and unknown values are ignored.

No target ever drops under 24 × 24 CSS px (WCAG 2.5.8): every scaled control floors its size at --ki-density-target-min, so in compact the extra-small and small sizes can coincide at 24px. Two tokens carry the step, and you can set your own: --ki-density-control-offset (added to block sizes) and --ki-density-space-scale (multiplies padding and gaps).

[data-ki-density='compact'] { --ki-density-control-offset: -4px; }

For touch-first surfaces — a kiosk, a mobile layout — declare touch instead:

<section data-ki-density="touch">…</section>

Touch is one +4px step (medium controls 40 → 44px, material3 fields 48 → 52px) with 44 × 44 CSS px pointer targets (WCAG 2.5.5, Apple’s HIG). Checkboxes, radios, switches, icon buttons and the alert’s dismiss control keep their painted size and their place: their target extends invisibly around them instead. Text, icons and container spacing do not change. Touch and compact nest in each other like any density, and --ki-density-target-min sets the target (48px for Material’s 48dp).

Kimen never switches to touch by itself. To follow the pointer, put the touch values on the page root in your own stylesheet:

@media (pointer: coarse) {
:root {
--ki-density-control-offset: var(--ki-space-xs);
--ki-density-space-scale: var(--ki-scale-unit);
--ki-density-target-min: var(--ki-size-target-touch);
}
}

Leave room between small touch controls: an extended target reserves no space, so two controls closer than 44px centre to centre share the overlap. The target is centred on what the control paints, so it also reaches past the control’s leading edge (up to 13px for an 18px checkbox) and can lie over content right before it; an ancestor that clips its overflow cuts it.

The semantic surface scale in the current scheme — each swatch reads its color from the live token, so flipping this site’s theme toggle restyles them:

Theme for this example
Color scheme for this example
s0
s1
s2
s3
s4
s5
<div style="display: flex; gap: 0.5rem; flex-wrap: wrap;">
<div style="inline-size: 5.5rem; block-size: 3.5rem; display: grid; place-items: center; border-radius: 0.5rem; border: 1px solid var(--ki-outline-low-em); background: var(--ki-surface-s0); color: var(--ki-text-med-em); font-family: var(--ki-typography-family-mono); font-size: 0.75rem;">s0</div>
<div style="inline-size: 5.5rem; block-size: 3.5rem; display: grid; place-items: center; border-radius: 0.5rem; border: 1px solid var(--ki-outline-low-em); background: var(--ki-surface-s1); color: var(--ki-text-med-em); font-family: var(--ki-typography-family-mono); font-size: 0.75rem;">s1</div>
<div style="inline-size: 5.5rem; block-size: 3.5rem; display: grid; place-items: center; border-radius: 0.5rem; border: 1px solid var(--ki-outline-low-em); background: var(--ki-surface-s2); color: var(--ki-text-med-em); font-family: var(--ki-typography-family-mono); font-size: 0.75rem;">s2</div>
<div style="inline-size: 5.5rem; block-size: 3.5rem; display: grid; place-items: center; border-radius: 0.5rem; border: 1px solid var(--ki-outline-low-em); background: var(--ki-surface-s3); color: var(--ki-text-med-em); font-family: var(--ki-typography-family-mono); font-size: 0.75rem;">s3</div>
<div style="inline-size: 5.5rem; block-size: 3.5rem; display: grid; place-items: center; border-radius: 0.5rem; border: 1px solid var(--ki-outline-low-em); background: var(--ki-surface-s4); color: var(--ki-text-med-em); font-family: var(--ki-typography-family-mono); font-size: 0.75rem;">s4</div>
<div style="inline-size: 5.5rem; block-size: 3.5rem; display: grid; place-items: center; border-radius: 0.5rem; border: 1px solid var(--ki-outline-low-em); background: var(--ki-surface-s5); color: var(--ki-text-med-em); font-family: var(--ki-typography-family-mono); font-size: 0.75rem;">s5</div>
</div>

When you need to customize a component, reach for surfaces in this order — if a consumer would ever need !important, that is an API bug to report:

  1. Tokens — reassign at :root (theme-wide) or on a subtree.
  2. ::part() — style exposed parts for one-off structural tweaks.
  3. Slots — replace content entirely.