Platform Kit

Status: Running today. @nimiplatform/nimi-kit is the shipped single-package authority for cross-app shared platform infrastructure (P-KIT-001..P-KIT-099).

The Platform Kit is the cross-surface layer that holds the design tokens, primitives, foundation modules, feature modules, logic modules, and infra modules that Desktop, Avatar, Web, and other governed apps all consume. It is the answer to: "where does the shared visual + interaction language live?"

Kit is one package. Every Nimi app reaches into it through subpath imports. Apps do not duplicate what Kit covers.

Package Authority

Rule	Value
Authority package	@nimiplatform/nimi-kit (single)
Subpath exports	/ui, /auth, /core/*, /telemetry/*, /features/*
Source location	kit/ at repo root, peer to apps/, sdk/, runtime/
Sub-module workspace manifests	NOT permitted (single workspace package)
Apps may duplicate Kit capabilities?	No

A Kit sub-module that wants to ship must register in tables/nimi-kit-registry.yaml with declared subpath, kind (foundation / feature / logic / infra), dependencies, peer_dependencies, exports, admission_status, owner. New sub-modules register before any consumer can import.

Module Kinds

Kind	Purpose	Example
foundation	Tokens + primitives + themes (Kit's bedrock)	ui (@nimiplatform/nimi-kit/ui)
feature	Bounded feature surface (components + hooks + adapters within one public surface)	auth (@nimiplatform/nimi-kit/auth)
logic	Pure-logic utility (no UI / no CSS)	core (@nimiplatform/nimi-kit/core/*)
infra	Infrastructure: telemetry, error boundaries, host glue	telemetry, shell/tauri

Layer Boundaries

Layer	Imports allowed	Imports forbidden
Kit sub-module	Other Kit sub-modules per declared dependencies	App-layer code (apps/**); runtime internal (runtime/internal/**)
App	Kit through admitted subpath imports	Kit-internal paths bypassing the public subpath

kit/shell/tauri/** is admitted as a non-npm Rust crate consumed via Cargo path dependency. It does not have package.json exports and does not carry an independent workspace package manifest.

What Kit Owns

Concern	Sub-module
Design tokens + primitives + themes (visual foundation)	ui
Auth components + hooks + storage + adapters	auth
Shared env / capability detection / OAuth helpers	core
Renderer-side telemetry + error boundaries	telemetry
Tauri host glue (runtime bridge, daemon lifecycle, session logging, oauth commands)	shell/tauri

For the design-language depth see Design Pattern. For the material-token catalog see Nimi UI Material.

What Kit Does Not Own

• Per-app layout (each app composes Kit primitives in its own way)
• App-specific UX or product flows (Desktop chat shape, Avatar shell, etc.)
• Runtime semantic authority (those are runtime/cognition contracts)
• Realm domain truth
• Backend execution

Kit provides the building blocks. Apps assemble.

Reader Scenario: A Mod Author Wants Buttons That Look Right

A mod author writing a Desktop mod wants their UI to look like the rest of Desktop.

1. Consume Kit primitives. The mod imports @nimiplatform/nimi-kit/ui for shared <Button>, <Surface>, <Dialog>, etc.
2. Use semantic tokens. Components consume --nimi-* CSS custom properties; do not redefine them.
3. Theme follows shared scheme. Mod imports the shared light / dark CSS plus exactly one app accent pack from @nimiplatform/nimi-kit/ui/themes/*-accent.css.
4. Visual consistency. The mod's UI inherits the same primitives
   • tokens as host Desktop, automatically.

The mod author did not redefine button variants. They composed admitted primitives.

Reader Scenario: An App Adds A Feature That Already Exists In Kit

An app needs OAuth flow handling.

1. Check Kit first. @nimiplatform/nimi-kit/auth provides auth components + hooks, parameterized through AuthPlatformAdapter.
2. Inject the adapter. App provides the platform-specific adapter (Tauri / web).
3. Use Kit's surface. The app does not implement OAuth from scratch.

This rule (P-KIT-001) keeps the surface area honest: Kit's job is to prevent N apps from each writing their own auth.

Reader Scenario: Adding A New Kit Sub-Module

A maintainer wants to add a new shared sub-module.

1. Register first. A new row lands in tables/nimi-kit-registry.yaml with the required fields and admission_status.
2. Pick a kind. foundation / feature / logic / infra.
3. Add source under kit/<subpath>. Single workspace package; no independent manifest.
4. Consumers may import. Only after registration; the boundary is enforced.

Sub-modules cannot ship dark, undocumented surface area.

What Kit Does Not Do

• It does not let apps redefine its primitives or tokens.
• It does not allow N parallel design systems.
• It does not consume app-layer code.
• It does not consume runtime internal code.
• It does not let provider-specific or app-specific UX leak into shared primitives.

Boundary Summary

Concern	Owner
Single-package authority + subpath registry	P-KIT-001..P-KIT-002
Source location + boundary	P-KIT-003
Foundation / feature / logic / infra module kinds	P-KIT-010..P-KIT-041
Design pattern (visual + interaction contracts)	P-DESIGN-* (separate page)
Material taxonomy + tokens	nimi-ui-material-contract.md (separate page)

Source Basis

• .nimi/spec/platform/kernel/kit-contract.md
• .nimi/spec/platform/kernel/tables/nimi-kit-registry.yaml
• .nimi/spec/platform/kernel/design-pattern-contract.md
• .nimi/spec/platform/kernel/nimi-ui-material-contract.md