lib.ui-kit-core
Core UI primitives and utilities
@lssm-tech/lib.ui-kit-corebun add @lssm-tech/lib.ui-kit-coreManifest 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, andui-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.
./interfacesis the shared compatibility layer for semantically matchingui-kitandui-kit-webexports../command-themeis 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()composesclsxwithtailwind-merge.- Changes here ripple into all UI packages even though the file count is small.
- This package should stay boring and predictable.
./ssr/subject-scopecarries an already resolved contractSubjectthrough 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, returnsundefinedoutside 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:
bun run ui-kit:compatThe 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:
SharedBoxPropsis the shared semantic wrapper contract. It intentionally carries onlyclassNametoday; consumers should not depend onBoxfor flex direction, default gap, or default alignment.SharedFlexStackPropsowns the cross-platform stack subset:gap,align,justify, andwrap.HStackandVStackshould consumeSharedFlexStackProps; new shared UI should pick one of them whenever direction matters.SharedStackPropsremains 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.
Related packages
@lssm-tech/lib.ui-kit@lssm-tech/lib.ui-kit-web@lssm-tech/lib.ui-link
Local commands
bun run lint:checkbun 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
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
Core UI primitives and utilities
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrm -rf distlintbun run lint:fixlint: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-testsprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit