Repository avatar
Other Tools
v0.1.1
active

kimen

io.github.kimen-dev/kimen

List and describe Kimen components, validate UI specs and render them as MCP Apps surfaces.

Documentation

Kimen

Kimen (Norwegian/Danish): the seed, the germ from which something grows.

ci License: Apache-2.0

An AI-first Web Components foundation for generative UI. Kimen ships 29 standards-first <ki-*> components, a layered design-token system with two complete themes, a neutral runtime catalog whose guarded renderer accepts or rejects agent-emitted UI specs fail-closed, and protocol adapters for A2UI and MCP Apps:

agent → JSON spec → validation → guarded renderer → <ki-*> components

Status: pre-v1. Everything above is implemented and gate-verified in CI; nothing is published to npm yet. The commands below are the exact contract the first release ships with, validated against packed tarballs on every release dry run (scripts/consumer-contract.mjs).

Explore: documentation site · Storybook workshop · landing with live re-theming

Quickstart

pnpm add @kimen/elements @kimen/tokens
# or: npm install @kimen/elements @kimen/tokens

Register each component from its direct subpath, then load the token stylesheet once — and, optionally, the page contract:

import { defineCustomElement as defineKiButton } from '@kimen/elements/ki-button';
import '@kimen/tokens/css'; // design tokens + color-scheme: onmars theme, light + dark
import '@kimen/tokens/css/base'; // optional page contract: page background, text color, body font

defineKiButton();
<ki-button variant="primary">Save</ki-button>

@kimen/tokens/css is the only requirement. Besides every --ki-* token it declares the color-scheme they resolve from, so the browser paints the canvas, scrollbars and native controls in the same scheme as the components: a page that loads nothing else stays legible in light and in dark (measured over all 29 components under a dark system preference). That declaration is a zero-specificity default — a color-scheme your own CSS sets on the page wins, and the tokens follow it.

@kimen/tokens/css/base is the opt-in page contract: it paints the page itself from the semantic tokens — background, text color and body font — and declares no color scheme.

Themes and color schemes

@kimen/tokens/css ships the default onmars theme and follows the system color scheme. To opt into the Material 3 reference theme, also load its stylesheet and select it with data-ki-theme; data-ki-color-scheme (light / dark) overrides the OS scheme for any theme. Both attributes work on the document root or on any element:

import '@kimen/tokens/css/material3';
<html data-ki-theme="material3" data-ki-color-scheme="dark">

Every visual value is a --ki-* custom property layered primitive → theme → semantic → component; themes reassign tokens, never component CSS. Details in the @kimen/tokens README.

Onmars color and surfaces

Onmars v2, Calma, pairs a paper ivory canvas with warm charcoal in dark mode. Ink anchors the primary action. Terracotta marks links, focus and selection. Crimson signals errors. Opaque fills, hairline borders and soft shadows give surfaces their depth.

Onmars typography

Instrument Sans leads the UI and body stack. Newsreader leads the display and serif stacks. The tokens specify the font families and fallbacks.

Imports from the package root (import { KiButton } from '@kimen/elements') are a deprecated compatibility facade: see docs/migrations/root-imports.md.

Generative UI

Runtime GenUI (A2UI and MCP Apps, which AG-UI streams also carry) injects agent-generated UI into applications you don't control. Web components are the one component technology that behaves identically in every host, and a closed, validated catalog is safer than letting an agent emit open HTML. Kimen ships both halves: @kimen/catalog validates agent-emitted UI specs against the machine-generated catalog and renders them through one guarded path — only catalog components render, only declared actions dispatch, no code path executes from spec data — and the protocol adapters translate A2UI messages and MCP Apps surfaces into that same path. Adapters are disposable by design; the catalog and components are the durable assets.

The boundary is open on both sides: createCatalog registers an application's own components behind a data-only JSON facade (validated as hostile input, deep-frozen, composable with the built-ins), and @kimen/emitter derives from any catalog the guidance an LLM integration needs — a system prompt with the usage guidance verbatim, a catalog-specialized JSON Schema with provider-strict lowerings, and a provider-neutral tool definition — plus the normalize-and-repair helpers that close the reliability loop. Emitter artifacts are advisory; validation and the guarded renderer stay the only enforcement points.

Packages

PackageStatusWhat it is
@kimen/elementsImplemented, unpublished29 <ki-*> Stencil web components
@kimen/tokensImplemented, unpublishedDesign tokens (DTCG), primitive → theme → semantic → component
@kimen/catalogImplemented, unpublishedNeutral catalog schema + guarded renderer (validateUiSpec, renderUiSpec, streaming)
@kimen/adapter-a2uiImplemented, unpublishedA2UI protocol adapter over the guarded renderer
@kimen/adapter-mcp-appsImplemented, unpublishedMCP Apps adapter: Kimen surfaces as self-contained ui:// resources
@kimen/mcp-serverImplemented, unpublishedMCP server over stdio: agents list the catalog, validate specs and render them as MCP Apps surfaces
@kimen/emitterImplemented, unpublishedEmitter kit: prompt, provider-lowered JSON Schema and tool definition from any catalog, plus normalize + single-round repair
@kimen/reactImplemented, unpublishedGenerated React bindings: typed props, event callbacks, controlled forms
@kimen/vueImplemented, unpublishedGenerated Vue 3 bindings with v-model on the form components
@kimen/angularImplemented, unpublishedGenerated Angular standalone components + ControlValueAccessors (APF, Angular ^22)
kimenPlaceholderFuture CLI / meta package

The current v1 publication contract covers exactly @kimen/elements and @kimen/tokens; whether the catalog and adapters publish at v1 is an open founder decision — see docs/releasing.md.

For agents

Kimen treats agent legibility as a deliverable. The repository root and @kimen/elements ship llms.txt, a short index in the llms.txt shape: what Kimen is, how to load it, when to use each component, and a link per component to one Markdown document with its attributes, slots, parts, events, methods, CSS custom properties, examples and when-to-use / when-not-to-use guidance. llms-full.txt is all of it in one file, and packages/elements/generated/custom-elements.json is the machine-readable Custom Elements Manifest. All of them are generated from component JSDoc and token sources, never hand-edited, and the code examples of the packaged llms.txt are executed against packed tarballs during release validation. Human-readable docs live at the documentation site.

Coding agents can also connect to Kimen directly: the kimen plugin carries two agent skills (kimen-components for ordinary pages, kimen-genui for the generative UI layer), and the kimen-mcp server lets an agent list the catalog, validate UI specs and render them. In Claude Code:

claude plugin marketplace add kimen-dev/kimen
claude plugin install kimen@kimen

Setup for Claude Code, Claude Desktop, Codex, Antigravity, OpenCode and other clients is in Connect your agent.

Quality bar

Every component ships with real-browser tests (three engines at release), zero axe-core violations (WCAG 2.2 AA + EN 301 549 target), a single-digit-KB size budget, tokens-only styling (no hardcoded visual values), and RTL support by construction. Run bash scripts/gates/gates-suite.sh for full local checks before a pull request. CI requires visual and cross-filesystem checks as part of the quality and release gates. It runs the part of the suite a change can affect, and the complete suite for shared infrastructure and nightly on main (see CONTRIBUTING.md).

For a quicker local pass, run bash scripts/gates/gates-suite.sh --affected. Nx selects projects and their dependents from committed, staged, unstaged and untracked changes since the merge base with origin/main. It runs their builds, unit tests, size checks, Chromium tests and browser wrapper tests where those targets exist. Set NX_BASE to use a different base. Changes to shared inputs, such as root configuration or gate scripts, trigger the full suite. Affected runs provide local feedback only.

On a non-Linux host the local browser suite reports how many visual specs it skips. Set KIMEN_RUN_VISUALS=1 to run them with your host's baselines. The local cross-filesystem documentation test skips if TMPDIR does not point to a writable directory on a different filesystem. To exercise that boundary on macOS, run bash scripts/gates/cross-device-tmpdir.sh -- bash scripts/gates/gates-suite.sh. A local skip contributes no release evidence.

Share local caches across worktrees

The default cache is private to each worktree under reports/cache. To share Nx task outputs, the pnpm store and Playwright binaries across local worktrees, set KIMEN_CACHE_ROOT to one private directory outside your home. For example, on macOS add export KIMEN_CACHE_ROOT="/Users/Shared/kimen-cache-$UID" to your shell startup file. The wrapper creates and validates the directory. It rejects symlink components and group- or world-writable cache directories. Nx project graph state, Vite state and gate evidence have separate worktree directories.

Use the wrapper when provisioning the shared store and Chromium binaries. Run the install in each worktree when switching it to the shared store.

bash scripts/gates/cache-env.sh -- pnpm install --frozen-lockfile
bash scripts/gates/cache-env.sh -- pnpm --filter @kimen/elements exec playwright install chromium

Governance

The repository operates under a constitution digest (.specify/memory/constitution.md): generated artifacts are regenerated, never hand-edited; styling is tokens-only; agent surfaces are versioned with the public API; the founder is the only merge gate. Agents working in the repo start at AGENTS.md.

Roadmap

See docs/roadmap.md for where the project is headed.

Contributing

External contributions are welcome and pass exactly the same gates as everything else: see CONTRIBUTING.md. Security reports: SECURITY.md.

License

Apache-2.0 · Copyright 2026 Marcela Gotta

  • available — Consumer catalog registration: your own components behind a JSON facade, validated and rendered through the same fail-closed guardrail
  • available — Emitter kit: model-agnostic prompt, catalog-specialized JSON Schema and tool definition so any LLM emits valid specs, with a single-round repair loop
  • available — Generated framework wrappers: @kimen/react, @kimen/vue and @kimen/angular with typed props, native events and each framework form idiom, drift-gated
  • available — Schema-constrained guarded renderer: untrusted UI specs render only through the neutral catalog, fail-closed
  • available — Kimen MCP server: over stdio, agents list and describe the catalog, validate UI specs with correctable issues and render them as MCP Apps surfaces through the guarded renderer
  • hardening — Changed-core mutation quality gate in hardening
  • available — A2UI protocol adapter: declarative A2UI messages render through the guarded renderer
  • available — MCP Apps adapter: Kimen surfaces reach MCP Apps hosts as self-contained ui:// resources rendered through the guarded renderer
  • available — Neutral runtime component catalog with schema-validated UI specs at the GenUI boundary
  • available — Machine-readable Web Components foundation with token-driven theming
NPM
@kimen/mcp-server
Install Command
npm install @kimen/mcp-server