Skip to content
ContractSpec
Start here

Package manual · platform

·Interfaces, presentations and design

lib.ui-kit-core

Core UI primitives and utilities

platformlibraryv6.0.4stablereact-nativeserverbunnode
@lssm-tech/lib.ui-kit-core
bun add @lssm-tech/lib.ui-kit-core
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

/hooks/useReducedMotion selects the web implementation under the browser condition, including when react-native is also active. Native alone selects AccessibilityInfo; Bun and Node retain the web implementation and its SSR fallback. Workspace source resolution follows the existing published condition order, and published export targets are unchanged.

@lssm-tech/lib.ui-kit-core is the shared foundation for the UI packages. It provides the low-level cn() utility plus the canonical shared interface layer used by ui-kit and ui-kit-web.

Website: https://contractspec.io

Installation

bun add @lssm-tech/lib.ui-kit-core

or

npm install @lssm-tech/lib.ui-kit-core

What belongs here

This package is intentionally small:

  • Very low-level, zero-surprise UI helpers shared across ui-kit, ui-kit-web, and ui-link.
  • Small shared utilities that are useful across multiple UI packages and do not belong in a component package.
  • Platform-neutral shared UI contracts under ./interfaces.

API map

  • root export: .
  • shared interfaces subpath: ./interfaces
  • server-only subject propagation port: ./ssr/subject-scope
  • utility subpath: ./utils
  • command theme class contract: ./command-theme
  • core function: cn(...inputs)

Operational semantics and gotchas

  • This package is intentionally tiny.
  • ./interfaces is the shared compatibility layer for semantically matching ui-kit and ui-kit-web exports.
  • ./command-theme is a narrow shared class contract for command palette/search-trigger color states. It exists only to keep native, web, and design-system command surfaces aligned on semantic theme tokens; it is not a general design-token bucket.
  • cn() composes clsx with tailwind-merge.
  • Changes here ripple into all UI packages even though the file count is small.
  • This package should stay boring and predictable.
  • ./ssr/subject-scope carries an already resolved contract Subject through request-local async scopes. AuthOS supplies the subject at the request edge; web SSR reads the same scope. It performs no authentication or policy decision, returns undefined outside a scope, and belongs only in Node server bundles. Existing AuthOS SSR entry points keep their signatures and strict missing-context error. This additive lower port removes the UI package's upward domain dependency.

Compatibility guard

ui-kit-core also owns the registry used to compare the native and web UI kit lanes. Run the repo-level guard before adding or changing shared ./ui/* surfaces:

bash
bun run ui-kit:compat

The guard compares packages/platform/ui/ui-kit and packages/platform/ui/ui-kit-web exported ./ui/* subpaths, exported symbols, and shared prop-shape contracts. Existing drift is recorded in scripts/ui-kit-compatibility-baseline.json; new drift should be fixed or deliberately accepted by refreshing that baseline in the same reviewed change. Shared component contracts should be declared here first under ./interfaces, then consumed from both UI kit packages.

Layout contract split

./interfaces separates neutral wrapper semantics from directional stack semantics so the web and native lanes can migrate Box safely:

  • SharedBoxProps is the shared semantic wrapper contract. It intentionally carries only className today; consumers should not depend on Box for flex direction, default gap, or default alignment.
  • SharedFlexStackProps owns the cross-platform stack subset: gap, align, justify, and wrap.
  • HStack and VStack should consume SharedFlexStackProps; new shared UI should pick one of them whenever direction matters.
  • SharedStackProps remains exported for compatibility while the staged Box neutral-default migration is underway.

Changing gap, align, justify, wrap, as, or the Box/stack split is a public compatibility decision. Update package docs, release capsules, and guard evidence in the same reviewed change.

When not to use this package

  • Do not use it for components.
  • Do not use it for design tokens.
  • Do not use it for router or link abstractions.
  • @lssm-tech/lib.ui-kit
  • @lssm-tech/lib.ui-kit-web
  • @lssm-tech/lib.ui-link

Local commands

  • bun run lint:check
  • bun run typecheck

Graph & Timeline Primitives

@lssm-tech/lib.ui-kit-core now exports platform-agnostic graph and timeline hooks and interfaces — pure TypeScript, no React or react-native imports.

Hooks: useGraphFilter, useGraphLayout, useGraphSelection, useAdaptiveGraphRenderer, useTimelineRange, useTimelineZoom

Interfaces: GraphNode, GraphEdge, GraphSelection, GraphCanvasProps, TimelineEvent, TimelineRange, TimelineProps, TimelineGraphProps, GraphLayoutKind

useAdaptiveGraphRenderer returns "svg" or "reactflow" based on a bounded node/edge threshold (default 300 nodes / 500 edges), enabling lazy-loading of GraphCanvasAdvanced in the web lane.

See AGENTS.md for full details.

Complete graph view contract ownership

The compatible ownership proposal places the complete existing Annotation, SavedView, and GraphExport declaration families in UiKitCore under ./data-views/annotation, ./data-views/saved-view, and ./data-views/graph-export. Legacy imports remain forwards to those same declarations and documentation objects. Existing constants, fields, defaults, helper behavior and tests are preserved. Source and publication roots include their existing platform conditions and the explicit Node condition.

The proposal also binds UI consumers to existing canonical Core, Kernel and DesignCatalog families. Qualification requires fresh task-bound adoption, owning production, declaration consumers and affected tests; this source checkpoint does not claim that execution.

Relationships

THIS PACKAGElib.ui-kit-core82 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

10 declarations

  • @types/d3-force

    ^3.0.10

  • @types/d3-hierarchy

    ^3.1.7

  • class-variance-authority

    ^0.7.1

  • clsx

    ^2.1.1

  • d3-force

    ^3.0.0

  • d3-hierarchy

    ^3.1.2

Declared capabilities

Lib Ui Kit Core

Core UI primitives and utilities

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrm -rf dist
  • lintbun run lint:fix
  • lint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../../scripts/biome.cjs check .
  • testbun test --pass-with-no-tests
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit