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):
- Primitive — raw ramps (
--ki-color-brand-500,--ki-space-md). Never consumed by components directly. - 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. - 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.
Themes
Section titled “Themes”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.
Onmars v2 (Calma)
Section titled “Onmars v2 (Calma)”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.
Color scheme
Section titled “Color scheme”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.
The page contract
Section titled “The page contract”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.
More contrast and less transparency
Section titled “More contrast and less transparency”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; }}Density
Section titled “Density”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.
Surfaces
Section titled “Surfaces”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:
<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>Customization order
Section titled “Customization order”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:
- Tokens — reassign at
:root(theme-wide) or on a subtree. ::part()— style exposed parts for one-off structural tweaks.- Slots — replace content entirely.