@nimiplatform/kit

The product-grade cross-app toolkit for Nimi apps. @nimiplatform/kit packages the shared UI primitives, auth flows, telemetry, shell glue, Platform catalog projections, and feature modules that every Nimi consumer needs, so app authors do not have to rebuild baseline styling, interaction shells, or platform wiring. The kit is a reusable projection of platform-governed design and integration contracts; canonical semantics remain in .nimi/spec/platform/ui-design-system.authority.yaml.

Installation

pnpm add @nimiplatform/kit

The kit depends on @nimiplatform/sdk. During the 0.x phase, SDK alignment is directional (see "Version Policy" below). React 19 is required; react-dom and react-i18next are optional peers.

Version Policy

@nimiplatform/kit publishes first at 0.1.0 and remains in a pre-1.0 iteration phase. Under semver, 0.x.y minor bumps may include breaking changes while the public surface matures. Breaking 0.x minor bumps still require migration notes in CHANGELOG.md.

Alignment with @nimiplatform/sdk is directional until SDK reaches 1.0.0. At that future event, kit must make an explicit 1.0.0 readiness decision; kit does not automatically claim stable-release semantics before then.

| Bump | Trigger | |---|---| | Patch | Compatible fix only, no public API change | | Minor | New export, compatible type widening, or breaking change during 0.x | | Major | Explicit 1.0.0 readiness decision, or post-1.0 breaking change |

Semver classification rules are documented in detail in kit/AGENTS.md under "Semver Discipline".

Reuse First

Before building app-local UI, shell glue, auth flows, telemetry, model configuration, chat, avatar, generation, commerce, or runtime-bound adapter code, check this README, the target module README, and the nearest owner contract. Reuse an existing @nimiplatform/kit export when it covers the baseline behavior; extend the kit surface first when the missing behavior is cross-app.

DESIGN.md Projection

kit/DESIGN.md is the generated Google DESIGN.md-style projection for Nimi Kit UI/UX work. It combines DESIGN.md-compatible YAML front matter with human-readable guidance for agents, but canonical authority remains in .nimi/spec/platform/ui-design-system.authority.yaml.

The generated design artifact set is:

• kit/DESIGN.md - compact agent-readable DESIGN.md projection.
• kit/design_tokens.json - DTCG-style token export for external tooling.
• kit/design-projection.json - full Nimi machine projection with every source token, theme value, primitive slot, variant, and source rule.
• kit/tailwind-theme.css - Tailwind v4 @theme projection for tooling and audits.

Runtime Kit styles are still generated by scripts/generate-nimi-ui-lib.mjs into kit/ui/src/generated/**; kit/tailwind-theme.css is an interoperability artifact, not the runtime source of truth.

Regenerate intentionally after admitted design authority changes:

pnpm generate:nimi-design-artifacts

Check for drift:

pnpm check:nimi-design-artifacts

Do not hand-edit kit/DESIGN.md or the root DESIGN.md; update the platform spec tables first and regenerate the projection.

Current Public Surface

The current package publishes 72 public subpath exports through kit/package.json:

• 9 UI entries (./ui, ./ui/glass, ./ui/motion, ./ui/a11y, ./ui/styles.css, ./ui/themes/light.css, ./ui/themes/dark.css, ./ui/themes/nimi-accent.css, and ./ui/themes/nimi-density-compact.css)
• 4 auth entries (./auth, ./auth/shell, ./auth/styles.css, ./auth/native-oauth-result-page)
• 9 core entries (./core/shell-mode, ./core/oauth, ./core/storage-json, ./core/json-value, ./core/offline-coordinator, ./core/notifications, ./core/desktop-open, ./core/runtime-capabilities, and ./core/sdk-contract)
• 7 shell entries (./shell/capabilities, ./shell/renderer/bridge, ./shell/renderer/bootstrap, ./shell/renderer/host, ./shell/electron/main, ./shell/electron/preload, and ./shell/electron/preload-cjs)
• 2 telemetry entries (./telemetry, ./telemetry/error-boundary)
• Feature entries across ./features/chat, ./features/avatar, ./features/agent-center, ./features/model-config, ./features/model-picker, ./features/generation, and ./features/agent-realtime

The complete npm subpath inventory is the exports object in kit/package.json.

Import Patterns by Sub-module

UI primitives

import { Button, DataTable, Pagination, Statistic, IconButton, cn } from '@nimiplatform/kit/ui';
import { GlassSurface, glassMaterial } from '@nimiplatform/kit/ui/glass';
import { NimiMotionProvider, nimiSpring, nimiOverlayPanelMotion, projectMomentum, usePrefersReducedMotion } from '@nimiplatform/kit/ui/motion';
import { FOCUS_RING_CLASS_NAME, VISUALLY_HIDDEN_CLASS_NAME, VISUALLY_HIDDEN_STYLE } from '@nimiplatform/kit/ui/a11y';

Themes

Kit's stylesheet is Tailwind 4 source CSS. Import it in the same CSS entry that imports Tailwind, so its @source directives contribute component classes to that entry's utilities. A separate JavaScript stylesheet import alongside an unrelated Tailwind entry does not compile those classes. Include a foundation theme as well; styles.css alone does not select surface/text colors.

@import 'tailwindcss';
@import '@nimiplatform/kit/ui/styles.css';
@import '@nimiplatform/kit/ui/themes/light.css';
/* swap or layer accent themes */
@import '@nimiplatform/kit/ui/themes/nimi-accent.css';

Available themes: light, dark, nimi-accent, and the nimi-density-compact density overlay (P-DESIGN-028). Theme tokens are projected from config/platform-nimi-ui-themes.yaml.

For an adopted App, verify the real model picker with a long list: the list scrolls, confirmation stays in the viewport, and foreground/background tokens resolve. Missing theme values or uncompiled utilities are integration failures; do not hide them with App-local dialog height or z-index overrides.

Auth

import {
  WebAccountAuthPage,
} from '@nimiplatform/kit/auth';
import { DesktopBrowserAuthGate } from '@nimiplatform/kit/auth/shell';
import '@nimiplatform/kit/auth/styles.css';

WebAccountAuthPage accepts the Realm browser-session adapter. The separate auth/shell subpath exposes DesktopBrowserAuthGate with only the Runtime account broker and OAuth code bridge; it exports no Web credential adapter.

Core

import { ShellMode } from '@nimiplatform/kit/core/shell-mode';
import { OAuthShellContract } from '@nimiplatform/kit/core/oauth';
import { classifyCapability } from '@nimiplatform/kit/core/runtime-capabilities';
import { getNimiNotificationBadgeKey } from '@nimiplatform/kit/core/notifications';

./core/* modules are React-free and renderer/runtime-safe.

Renderer shell

import { invokeTauri } from '@nimiplatform/kit/shell/renderer/bridge';
import { ensureNimiShellRuntimeBridgeInstalled } from '@nimiplatform/kit/shell/renderer/bootstrap';

Renderer shell APIs are host-neutral; Tauri and Electron host implementations live behind injected bridge hooks. Runtime account operations flow through the protected bridge; renderer code cannot load, save, clear, or persist Runtime account tokens.

Electron shell

import {
  createElectronRuntimeBridgeCommandNames,
  type NimiElectronHostCommandPolicy,
} from '@nimiplatform/kit/shell/electron/main';
import { installNimiElectronRuntimeBridge } from '@nimiplatform/kit/shell/electron/preload';

Electron shell APIs are for main/preload host code only. Renderer application code uses SDK electron-ipc plus @nimiplatform/kit/shell/renderer/*. Host-owned commandPolicy hooks may deny selected standard or app-domain commands before their handlers run; policy denials surface as structured fail-closed shell errors rather than pseudo-success.

Desktop-supervised third-party apps use registerNimiElectronAppBridge. Its optional appCommandHandlers map registers exact native product commands under the app's own authority. Those handlers receive the fixed renderer URL/origin checks, cannot occupy the reserved nimi.shell.* namespace, and never create a Nimi permission row or prompt. A handler must not proxy protected Runtime, Realm, account, credential, Agent, or Cognition operations.

Tauri shell crate

use nimi_shell_tauri::capabilities::platform_catalog::ai_profile_factory;
use nimi_shell_tauri::capabilities::platform_projection::factory_profile_index;

Telemetry

import { emitTelemetry, traceSession } from '@nimiplatform/kit/telemetry';
import { ShellErrorBoundary } from '@nimiplatform/kit/telemetry/error-boundary';

Features

import { useAppAiChatSession } from '@nimiplatform/kit/features/chat/runtime';
import { useRealmChatComposer } from '@nimiplatform/kit/features/chat/realm';
import { CanonicalConversationShell } from '@nimiplatform/kit/features/chat/components/canonical-conversation-shell';
import { AvatarStage } from '@nimiplatform/kit/features/avatar';
import { AgentCenter } from '@nimiplatform/kit/features/agent-center';
import { ModelConfigAIConfigSurface } from '@nimiplatform/kit/features/model-config';
import { ModelPickerDialog } from '@nimiplatform/kit/features/model-picker';
import { useRuntimeGenerationPanel } from '@nimiplatform/kit/features/generation/runtime';
import { AgentRealtimeEntry, createBrowserAgentRealtimeHostMediaPort } from '@nimiplatform/kit/features/agent-realtime';

Model Config requires one explicit owner/consumer context and host-supplied canonical reads/mutations. Model Picker is non-committing and consumes only owner-supplied candidates; its retired Runtime route-provider export is not restored.

Generation keeps modality request/result contracts, but execution fails closed until Runtime exposes owner-driven Scenario submission without caller-supplied model, route, binding, or configuration truth.

Each feature exposes the four-surface taxonomy where applicable:

• headless: logic, state, adapter contracts (no UI)
• ui: opinionated React surfaces built on kit primitives
• runtime: bindings to the local AI / runtime engine
• realm: bindings to the logged-in platform business services

SDK Contract Boundary

Every kit consumption of @nimiplatform/sdk* routes through one file: ./core/sdk-contract. If you need an SDK type or value inside kit code, import it from @nimiplatform/kit/core/sdk-contract (kit-internal) rather than @nimiplatform/sdk. App consumers should continue importing directly from @nimiplatform/sdk — the single-boundary rule applies inside kit only.

Why: when the upstream SDK reshapes a type, the breakage surfaces as a compile-time error in one file, not deep in feature code. The file also documents the admitted dynamic-import escape hatch used by kit/features/chat/src/runtime/orchestration.ts.

Accessibility

@nimiplatform/kit/ui/a11y ships the kit's accessibility primitives:

• FOCUS_RING_CLASS_NAME is applied to Button and IconButton by default, providing a keyboard-visible focus ring that meets WCAG 2.1 AA contrast.
• VISUALLY_HIDDEN_CLASS_NAME and VISUALLY_HIDDEN_STYLE hide content from sighted users while keeping it available to assistive tech.
• useFocusTrap enforces modal focus containment.

@nimiplatform/kit/ui/motion ships the admitted animation substrate (P-DESIGN-027 / nimi-ui-motion-contract.md):

• motion, AnimatePresence, useReducedMotion — re-exported from the motion package so governed surfaces never adopt a parallel animation library.
• NimiMotionProvider — wires OS reduced-motion into the substrate.
• nimiSpring() / NIMI_SPRING_DEFAULT / NIMI_SPRING_MOMENTUM — spring presets mirrored from the motion.spring_* tokens.
• nimiOverlayPanelMotion() / nimiOverlayBackdropMotion() — symmetric, spring-based overlay enter/exit grammar.
• projectMomentum() / nearestSnapTarget() / normalizeReleaseVelocity() / shouldCommitGesture() — gesture velocity handoff and momentum projection math.
• usePrefersReducedMotion() — SSR-safe hook that respects prefers-reduced-motion: reduce.
• NIMI_MOTION_DURATIONS_MS / NIMI_MOTION_EASINGS — TS mirror of the spec motion.* duration/easing tokens; divergence is design drift.

Authors building new animations MUST gate non-essential motion behind reduced-motion handling and use the admitted spring presets.

Theming Integration

The kit ships base styles plus theme overlays. Apply exactly one base theme (light.css or dark.css) and optionally the Nimi accent overlay (nimi-accent.css). Themes set CSS custom properties that kit primitives consume; do not override the property names — extend by adding scoped overlays.

Contributing

See kit/AGENTS.md for module boundaries, semver discipline, SDK contract boundary rules, and verification commands.

Verification

pnpm --filter @nimiplatform/kit build
pnpm --filter @nimiplatform/kit test
pnpm check:nimi-kit