Kern UI — by Xoroh

Status: current

An open Material Design 3 design system: tokens, web and native components, documentation, and tooling. MIT licensed and usable by people and AI agents.

• Documentation: https://kern.xoroh.org
• Hub: https://xoroh.org

Install

0.1.0 Preview: packages are unpublished (0.0.0), so every registry command below runs at release. The route that works today is the source install — scaffold from a checkout and vendor what you need:

bun <checkout>/packages/kern-cli/src/kern.ts init my-app
bun <checkout>/packages/kern-cli/src/kern.ts add button --dest components/kern

Registry path (available at release):

bun add @xoroh/kern

Web components need @base-ui/react, react, react-dom, and Tailwind CSS v4 with utilities mapped to the MD3 roles:

import "@xoroh/kern/theme";

import { Button } from "@xoroh/kern";

export function Save() {
  return <Button variant="primary">Save</Button>;
}

React Native:

import { Button, KernThemeProvider } from "@xoroh/kern-native";

export function Save({ onPress }: { onPress: () => void }) {
  return (
    <KernThemeProvider>
      <Button variant="primary" onPress={onPress}>
        Save
      </Button>
    </KernThemeProvider>
  );
}

Per-package detail lives in each package's README.

Packages

Package	Directory	What it is
@xoroh/kern-tokens	packages/kern-tokens	Tokens (tokens.json), theme presets, contrast overlays, tones, feedback spec, variant registry, DTCG 2025.10 interchange (dtcg.json), Xoroh compatibility preset. Platform-free: no React, no DOM
@xoroh/kern	packages/kern	Web components (React, on Base UI) + the web theme runtime
@xoroh/kern/start	packages/kern/src/start	Web composition: blocks, top app bar, navigation, panes, scaffolds
@xoroh/kern-native	packages/kern-native	React Native components (StyleSheet + tokens) + the native scheme hook
@xoroh/kern-icons	packages/kern-icons	Material Symbols registry and the Icon renderer (web + native)
@xoroh/kern-mcp	packages/mcp	MCP server: components, tokens, themes, icons, blocks, install plans, validation
@xoroh/kern-contracts	packages/kern-contracts	Versioned contract schema: provider/component/block/icon/install metadata types + validators. Pure: no React/DOM/RN
@xoroh/kern-cli	packages/kern-cli	kern installer (init/add/list/diff/upgrade) + programmatic API; transactional installs, receipt v2, bundled registry payload

Seven packages publish; each versions independently.

Apps

• apps/site/ — kern.xoroh.org (TanStack Start): the documentation site. It imports and dogfoods @xoroh/kern, @xoroh/kern-tokens, @xoroh/kern-icons, and @xoroh/kern/start.
• apps/mobile/ — "Kern": an Expo host wiring the native theme and fonts.

Documentation

Where	What
https://kern.xoroh.org	Product docs for users: getting started, components, theme, guides
docs/	Contributor docs: architecture, parity, releases, conventions
.agents/skills/	Agent knowledge: kern (design authority), docs (upkeep discipline)

Direction

• docs/VISION.md — north star, principles, non-goals, quality bar.
• docs/decisions/ — owner decisions (ADR per decision).
• docs/IDEAS.md — owner ideas not yet decided.
• docs/architecture/kern-axis-migration-and-roadmap.md — the single source for planned work.

Contributing

Read CONTRIBUTING.md first — it lists the per-PR requirements (changeset, docs in the same change, lint, tests, conventional commits). docs/architecture.md explains how the packages fit together, and AGENTS.md routes an agent to the right skill.

Development

bun install
bun run build          # generators + all package builds
bun run lint
bun run typecheck
bun run test:all
bun run check:kern       # M3 contract: roles, tokens, shape scale
bun run check:contrast # WCAG across presets x modes x contrast levels
bun run check:publish  # publint + are-the-types-wrong, all 6 packages

License

MIT License — see LICENSE.