Skip to content
Kimenpre-v1

Guide

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.

Install

Section titled “Install”
Terminal window
npm install @kimen/elements @kimen/tokens

Load a theme — and the page contract

Section titled “Load a theme — and the page contract”

Two stylesheets belong in every page: a theme (css is the default onmars theme) and the page contract (css/base):

import '@kimen/tokens/css'; /* onmars theme, light + dark */
import '@kimen/tokens/css/base'; /* page contract: color-scheme + page colors */

The page contract declares color-scheme, paints the page from --ki-surface-s0 / --ki-text-high-em and sets the body font family. A token stylesheet alone cannot declare color-scheme, so without the page contract a dark-preference visitor gets dark component foregrounds on a canvas the browser still paints light — measured, 14 of 29 components fall below 4.5:1 contrast in that combination. Load the contract, or pin the page with data-ki-color-scheme="light". Doing neither is the one combination the library cannot render legibly. See Themes & color schemes for the full contract.

Register the elements

Section titled “Register the elements”

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();

Use a component

Section titled “Use a component”
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.

Color schemes

Section titled “Color schemes”

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

A second theme, one attribute

Section titled “A second theme, one attribute”

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.

Next steps

Section titled “Next steps”

Privacy