Skip to content
Kimenpre-v1documentation home
Color scheme

Getting started

Kimen ships two packages you install together: @kimen/elements (the ki-* web components) and @kimen/tokens (the design-token stylesheets that give them their appearance). Components resolve every visual value from tokens, so loading a token stylesheet is not optional styling — it is the styling.

npm install @kimen/elements @kimen/tokens

One stylesheet is required: a theme (css is the default onmars theme). The page contract (css/base) is an optional addition:

import '@kimen/tokens/css'; /* onmars theme + color-scheme, light + dark */
import '@kimen/tokens/css/base'; /* optional page contract: page background, text color, body font */

The theme stylesheet declares every --ki-* token and the color-scheme they resolve from, so the browser paints its canvas, scrollbars and native controls in the same scheme as the components: a page that loads nothing else stays legible for a visitor who prefers dark — measured across the component suite. That declaration is a default with zero specificity, so a color-scheme your own CSS sets on the page wins and the tokens follow it.

The page contract paints the page itself from the tokens — background from --ki-surface-s0, text from --ki-text-high-em, and the body font family. It declares no color scheme. See Themes & color schemes for the full contract.

Register everything at once with the lazy loader (each component’s code loads on first use):

import { defineCustomElements } from '@kimen/elements/loader';
defineCustomElements();

Or register only what you use, tree-shakably, from each element’s subpath:

import { defineCustomElement as defineKiButton } from '@kimen/elements/ki-button';
defineKiButton();
Theme for this example
Color scheme for this example
Save changes
<ki-button variant="primary" tone="success" size="md">
Save changes
</ki-button>

That is the whole model: HTML in, standard DOM events out. Form controls participate in native <form> submission with no framework bindings — see Framework integration.

Both themes follow the operating system by default and can be forced either way with one attribute — no runtime code involved:

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

The material3 reference theme proves the theming model: load its stylesheet and set one attribute, and every component re-skins with zero component changes.

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

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

  • Themes & color schemes — the theming model and the page contract in depth.
  • Design tokens — the token layers and how to customize without forking.
  • Components — the element library with live examples and generated API tables.
  • Storybook workshop — every component, every state, with theme and scheme toolbars.