admin

Joined on 2026-02-18

@assemblcorp/kernel (1.0.16)

Published 2026-04-08 17:13:01 +00:00 by admin

Set up this registry in your project .npmrc file:

@assemblcorp:registry=

To install the package using npm, run the following command:

npm install @assemblcorp/kernel@1.0.16

or add it to the package.json file:

"@assemblcorp/kernel": "1.0.16"

For more information on the npm registry, see the documentation.

@assemblcorp/kernel

Core shared kernel for JAX-UI token, validation, and adapter logic.

Purpose

Provides the repo’s neutral source of truth for token contracts, shared validation, and build/runtime adapters. It underpins @assemblcorp/ui and related tooling without pushing UI concerns into lower-level packages.

4-Tier Architecture

src/
├── 1-primitives/     # Tier 1: Raw design values (colors, spacing, typography)
│   ├── branded-types/    # Type-safe branded primitives
│   ├── constants/        # Static values
│   └── definitions.ts    # primitiveTokens, layerTokens, containerTokens
│
├── 2-core/           # Tier 2: Type definitions & utilities
│   ├── css-utils/        # CSS layer wrapping, variable generation
│   ├── dtcg-schema/      # DTCG 2025.10 schema definitions
│   ├── modes/            # Light/dark mode utilities
│   ├── token-types/      # Token type definitions, parsers, utilities
│   └── validators/       # CSS and token validation
│
├── 3-features/       # Tier 3: Token builders & introspection
│   ├── builders/         # Semantic token builders
│   ├── fluid/            # Fluid typography & spacing (Utopia-aligned)
│   └── introspection/    # Runtime token inspection
│
└── 4-adapters/       # Tier 4: Platform-specific integrations
    ├── terrazzo/         # DTCG export, Tailwind resolver, elevation plugins
    └── web-react/        # Web-specific React utilities

Data flows unidirectionally: Primitives → Core → Features → Adapters

What It Contains

Tier 1: Primitives

Design tokens: primitiveTokens, layerTokens, containerTokens
Branded types: PrimitiveColorToken, PrimitiveSpacingToken, PrimitiveRadiusToken
Type constructors: asPrimitiveColorToken(), asRadiusToken(), etc.

Tier 2: Core

Token types: SemanticTokenSet, ModeSemanticTokens, PrimitiveTokenSet
CSS utilities: wrapInLayer(), tokenIdToCssVar(), cssVarRef()
Validators: validateCSSSize(), validateColorFormat(), WCAG contrast checks
DTCG schema: Shadow types, color parsers, dimension utilities

Tier 3: Features

Fluid scales: Utopia-aligned clamp() generation for spacing & typography
Token builders: Semantic token construction utilities
Introspection: Runtime token inspection and extraction

Tier 4: Adapters

Terrazzo plugins: DTCG export, Tailwind @theme resolver, elevation CSS
Config utilities: createVariantSelector(), parseContextString(), etc.

Dependencies

{
  "dependencies": {
    "neverthrow": "catalog:",
    "radashi": "catalog:",
    "tailwind-merge": "catalog:",
    "tailwind-variants": "catalog:",
    "zod": "catalog:"
  }
}

There is no separate runtime @assemblcorp/shared workspace package here; shared primitives now live inside kernel-owned boundaries such as src/0-shared/.

Key Exports

Design Tokens

import {
  // Tier 1: Primitives (from 1-primitives/definitions.ts)
  primitiveTokens,    // Colors, spacing, typography, radii, shadows, transitions
  layerTokens,        // CSS @layer definitions
  containerTokens,    // Container query definitions

  // Tier 4: Semantics (from 4-adapters/terrazzo/design-tokens.ts)
  semanticTokens,     // Intent-based color aliases (primary, secondary, error, etc.)
  componentTokens,    // Component-specific token applications

  // Token Utilities
  resolveSemanticToken,   // Resolve token path for theme
  getComponentTokens,     // Get component tokens for theme
} from '@assemblcorp/kernel/tokens'

Terrazzo & DTCG Utilities

import {
  // DTCG Export
  tokensToDTCG,              // Convert tokens to DTCG JSON format
  generateResolverTokenFiles, // Generate resolver token files

  // Elevation (DTCG shadow format)
  getElevationTokens,        // Get elevation tokens for mode
  getAllElevationTokens,     // Get all elevation tokens

  // Config Utilities
  createVariantSelector,     // Create theme variant selectors
  parseContextString,        // Parse context strings (e.g., "arctic-dark")
  tokenIdToCssVar,           // Convert token ID to CSS variable name
  cssVarRef,                 // Create CSS var() reference
} from '@assemblcorp/kernel/tokens'

CSS Processing Utilities

Hybrid CSS processing using LightningCSS (transforms) and CSSTree (analysis):

import {
  // CSSTree: Analysis & Extraction
  extractCSSVariables,       // Extract all CSS custom properties
  extractCSSVariablesFiltered, // Extract with pattern filtering
  extractTokensByCategory,   // Categorize tokens (colors, spacing, etc.)
  findVariableUsages,        // Find all usages of a variable
  validateCSS,               // Validate CSS syntax

  // LightningCSS: Transforms & Minification
  processCSS,                // Process CSS with transforms
  minifyCSS,                 // Minify CSS output
  processWithOklchFallbacks, // Generate OKLCH color fallbacks
  bundleCSS,                 // Bundle multiple CSS files
  detectModernFeatures,      // Detect oklch, nesting, etc.
  getDefaultTargets,         // Get browser targets from browserslist

  // Types
  type CSSVariable,
  type ExtractedTokens,
  type TransformResult,
  type ValidationResult,
} from '@assemblcorp/kernel/css-processing'

When to use each library:

CSSTree: CSS analysis, token extraction, validation, linting
LightningCSS: CSS transformation, minification, OKLCH fallbacks

Types

import type {
  // Branded primitives
  PrimitiveColorToken,
  PrimitiveSpacingToken,
  PrimitiveRadiusToken,

  // Token sets
  PrimitiveTokenSet,
  SemanticTokenSet,
  ModeSemanticTokens,

  // DTCG types
  DTCGShadowToken,
  DTCGShadowValue,
  ElevationLevel,
} from '@assemblcorp/kernel/tokens'

Usage Examples

Access Design Tokens

import { primitiveTokens, semanticTokens } from '@assemblcorp/kernel/tokens'

// Primitive values
const primaryColor = primitiveTokens.color.blue[500]
const spacing = primitiveTokens.spacing[4]

// Semantic tokens (light/dark mode)
const buttonBg = semanticTokens.light.color.primary.base

Generate CSS Variables

import { tokenIdToCssVar, cssVarRef } from '@assemblcorp/kernel/tokens'

// Token ID → CSS variable name
tokenIdToCssVar('semantic.color.primary.base')  // '--color-primary-base'

// Create CSS var() reference
cssVarRef('semantic.color.primary.base')        // 'var(--color-primary-base)'

Build & Test

pnpm -C packages/kernel build      # Build package
pnpm -C packages/kernel typecheck  # Type checking
pnpm -C packages/kernel test       # Run tests

Performance

Type-checking time: <100ms (minimal dependencies)
Tests: Fast execution
Zero circular dependencies - enforced by 4-tier architecture

Architecture

4-Tier Data Flow

┌─────────────────┐
│  1-primitives   │  Raw design values (no semantic meaning)
│  definitions.ts │  primitiveTokens, layerTokens, containerTokens
└────────┬────────┘
         │ imports
         ▼
┌─────────────────┐
│    2-core       │  Type definitions, validators, CSS utilities
│  token-types/   │  DTCGShadowValue, tokenIdToCssVar(), wrapInLayer()
└────────┬────────┘
         │ imports
         ▼
┌─────────────────┐
│   3-features    │  Token builders, fluid scales, introspection
│  fluid/         │  Utopia-aligned clamp() generation
└────────┬────────┘
         │ imports
         ▼
┌─────────────────┐
│   4-adapters    │  Platform-specific integrations
│  terrazzo/      │  DTCG export, Tailwind resolver, elevation CSS
└─────────────────┘

Dependency Order

kernel sits below UI, theme-runtime, and tooling consumers. Lower-level shared helpers are exposed from kernel-owned entrypoints such as @assemblcorp/kernel/shared.

Key Design Principles

Unidirectional data flow: Lower tiers never import from higher tiers
Single responsibility: Each tier has a clear purpose
No circular dependencies: Enforced by tier structure
DTCG 2025.10 compliant: Shadow tokens, color format, composite types

Testing

pnpm -C packages/kernel test     # Run tests

Test coverage includes:

Public API boundary tests
DTCG shadow token format
Config utilities
CSS layer generation
Elevation migration integration

Part of: @assemblcorp monorepo | Status: Production | License: MIT

Dependencies

ID	Version
neverthrow	^8.2.0
radashi	^12.7.2
tailwind-merge	^3.5.0
tailwind-variants	^3.2.2
zod	^4.3.6

Development Dependencies

ID	Version
@terrazzo/cli	2.0.0
@terrazzo/parser	2.0.0
@terrazzo/plugin-css	2.0.0
@terrazzo/plugin-css-in-js	2.0.0
@terrazzo/plugin-js	2.0.0
@terrazzo/plugin-tailwind	2.0.0
@types/css-tree	^2.3.11
@typescript/native-preview	7.0.0-dev.20260327.2
css-tree	^3.2.1
tsdown	^0.21.7
type-fest	^5.5.0
typescript	npm:@typescript/native-preview@7.0.0-dev.20260327.2
vite-plus	^0.1.15
vitest	npm:@voidzero-dev/vite-plus-test@latest

Details

npm

2026-04-08 17:13:01 +00:00

560

Project Site

MIT

latest

958 KiB

Assets (1)

kernel-1.0.16.tgz 958 KiB

Versions (9) View all

1.0.16

2026-04-08

1.0.15

2026-04-08

1.0.14

2026-04-03

1.0.13

2026-04-02

1.0.12

2026-04-01

@assemblcorp/kernel (1.0.16)

Installation

About this package

@assemblcorp/kernel

Purpose

4-Tier Architecture

What It Contains

Tier 1: Primitives

Tier 2: Core

Tier 3: Features

Tier 4: Adapters

Dependencies

Key Exports

Design Tokens

Terrazzo & DTCG Utilities

CSS Processing Utilities

Types

Usage Examples

Access Design Tokens

Generate CSS Variables

Build & Test

Performance

Architecture

4-Tier Data Flow

Dependency Order

Key Design Principles

Testing

Dependencies