Kontour UI

The shared design-token and component layer for Kontour product interfaces.

@kontourai/ui

Use Kontour UI when you are building a Kontour product interface (Surface Console, Flow Console, Survey Review Workbench, Station, or a custom operator surface) and need to stay visually consistent with the --k-* token contract without copying CSS by hand. If you are building a general-purpose application with its own design system, you do not need this package.

Kontour UI ships three layers:

• @kontourai/ui/tokens — CSS custom properties for any renderer, no framework required.
• @kontourai/ui/react — class-driven React primitives: display (Badge, Button, Panel, Metric, Progress, Skeleton, Spinner, StatusBadge, StatusBar, Topbar, Empty, ProductIcon), form controls (Field, Input, Textarea, Select, Checkbox, Toggle), and overlays/feedback (Dialog, Toast, ToastHost, Tooltip, Popover) that read the token contract.
• @kontourai/ui/elements — light-DOM web-component wrappers for vanilla products.

Package docs:

• docs/consumer-guide.md covers React, custom elements, static HTML, theme classes, and vendored asset sync.
• docs/release-readiness.md records the release and adopter verification matrix.
• docs/gallery.html is the canonical static gallery for React/custom-element parity.

Themes

Apply one product theme class on a stable root element to set the product identity:

<main class="theme-survey">...</main>

Theme class	Product	Brand accent	Design intent
theme-survey	Survey / Review Workbench	#5ce0c6 teal	Evidence-forward; minimal overrides on the default dark shell
theme-console	Kontour Console	#c9ff4a lime-green	Dense operator plane; condensed font, zero radius, high-contrast palette
theme-flow	Flow	#2f88a6 blue	Process-transparency; cool accent on the default dark shell
theme-surface	Surface	#14a37a green	Trust-state inspection; earthy-green accent on the default dark shell

All themes support [data-theme="light"] for light-mode overrides. See docs/gallery.html for rendered examples of each theme in both modes.

React

Import primitive styles once at your app root:

import "@kontourai/ui/react/styles.css";

Then use the primitives:

import { Badge, Button, Panel, StatusBadge, Topbar } from "@kontourai/ui/react";

Custom elements

Load the element module for vanilla or web-component-based products:

<script type="module" src="./vendor/ui/dist/elements/elements/src/index.js"></script>

Then render:

<k-badge value="verified"></k-badge>
<k-status-badge status="connected"></k-status-badge>
<k-button label="Accept" variant="positive"></k-button>

Token import

Import the full token layer:

@import "@kontourai/ui/tokens";

That one import is sufficient: it pulls in the base tokens, the theme classes, and the @font-face rules for the brand faces. The individual files stay exported for consumers that compose them by hand:

@import "@kontourai/ui/fonts.css";
@import "@kontourai/ui/tokens.css";
@import "@kontourai/ui/themes.css";

Skipping fonts.css gives you the --k-font-* variables without the faces they name, and the surface silently renders in fallback typography.

Fonts

The brand faces ship inside the package as woff2 and are declared with real @font-face rules — nothing is fetched from a third party at render time. A product with default-src 'self', the right posture for a tool handling someone's documents, gets the brand typography with no CSP allowance and no network request.

Token	Family	Weights	License
--k-font-display	Fraunces (variable)	100–900	SIL OFL 1.1
--k-font-ui	Hanken Grotesk (variable)	100–900	SIL OFL 1.1
--k-font-mono	IBM Plex Mono	400, 500, 600	SIL OFL 1.1

Coverage is latin + latin-ext; anything outside those ranges falls through to the fallback stacks in tokens.css. Licenses ship alongside the files, and tokens/fonts/README.md records provenance. node scripts/vendor-fonts.mjs regenerates both the files and tokens/fonts.css.

For static HTML consoles served without a bundler, add a local package dependency and copy the CSS assets into the product's asset tree during build or setup:

{
  "devDependencies": {
    "@kontourai/ui": "file:../ui"
  }
}

<link rel="stylesheet" href="./vendor/ui/tokens/index.css">
<link rel="stylesheet" href="./vendor/ui/react/styles.css">

Products should style components with --k-* variables and treat the product theme class as the product identity boundary. Domain status words map to the shared semantic scale: positive, caution, negative, active, and neutral.

Checks

• npm run check:tokens verifies the token/theme contract and keeps React styles token-only.
• npm run check:exports builds and verifies package export targets, ESM output, declaration files, package naming, and framework-free element output.
• npm run check:readiness verifies release docs, gallery, package metadata, and adopter contract markers.
• npm run check:pack previews package contents with npm pack --dry-run.
• npm run verify runs all package readiness checks.