Kontour UIThe shared design tokens, React primitives, and web components for Kontour product interfaces.

Kontour UI Context#

Kontour UI is @kontourai/ui, the shared presentation layer for Kontour product interfaces. It owns the --k-* design-token contract, framework-specific primitives that consume those tokens, and package artifacts that downstream products import or vendor. "Console Kit" is the package's former product name; retain it only in historical decisions, audits, and compatibility identifiers.

Product Vocabulary#

  • Token contract: CSS custom properties under tokens/. Product surfaces should style with --k-* variables instead of hard-coded local design values. Token changes are cross-product changes.
  • Theme classes: Product identity classes in tokens/themes.css: theme-console, theme-flow, theme-station, theme-survey, and theme-surface. Apply one theme class on a stable root; use [data-theme="light"] for light-mode overrides.
  • React primitives: Components exported from react/ through @kontourai/ui/react. Display primitives (Badge, Button, Panel, Metric, Progress, Skeleton, Spinner, StatusBadge, StatusBar, Topbar, TrustState, TrustBasis, Empty, ProductIcon), form controls (Field, Input, Textarea, Select, Checkbox, Toggle), and overlays/feedback (Dialog, Toast, ToastHost, Tooltip, Popover). They are class-driven and read the shared token contract.
  • Stateful-primitive convention: Most primitives are pure element factories. Stateful ones (e.g. Dialog) may use React hooks — they run under the consumer's real React runtime. The package verifies their behavior through the mirrored web component (e.g. k-dialog) in the browser harness, not the factory-call smoke check; both share the same class contract.
  • Web components: Light-DOM custom elements in elements/, exported through @kontourai/ui/elements. They reuse the same class/style contract as the React primitives.
  • Generated dist/: Build output for package exports and declarations. Do not hand-edit dist/; regenerate it with package checks when code changes require it.
  • Semantic scale: Product-specific status words map to shared UI tones: positive, caution, negative, active, and neutral.
  • Trust states: Surface's claim statuses as presentation states: unknown, proposed, assumed, verified, stale, disputed, superseded, rejected, revoked, with Surface's display names as default labels. Separate from the tones and from product accents; each has its own --k-trust-* tokens and non-color cue. @kontourai/surface is a test-only devDependency that check:surface-parity compares against.
  • Trust basis: the muted line after a trust-state chip saying how the status was established. Surface computes it (claimBasisView in @kontourai/surface/display); TrustBasis / k-trust-basis render that TrustBasisView as given and never recompute facets. Caveats get a dashed underline (--k-basis-caveat-decoration), never a color; the line is never blank.

Boundaries#

Kontour UI defines shared presentation. It does not own product domain workflows, copy strategy, data fetching, routing, or app-specific state machines in downstream products.

Downstream adopters may import package exports or vendor copied assets, but they remain responsible for their own build, drift checks, and product-specific verification. When changing tokens, themes, primitive class names, package exports, or generated package shape, treat the change as adopter-facing and run the repo checks that match that surface.

Source Map#

  • AGENTS.md - agent-facing repo instructions and verification commands.
  • DESIGN.md - design constitution: roles, rules, and OPEN decisions; front matter generated from tokens/ (ships in the package).
  • README.md - package overview, installation shape, theme list, and consumer examples.
  • docs/consumer-guide.md - adopter guidance for React, custom elements, static HTML, theme classes, and vendored assets.
  • docs/release-readiness.md - package and adopter verification matrix.
  • tokens/ - token contract, fonts, themes, and aggregate CSS entry points.
  • react/ - React primitive styles and source.
  • elements/ - web-component wrappers and demo.
  • dist/ - generated package output.

Source: CONTEXT.md