@tekton-ui/core
Advanced tools
Minimal design system pipeline - Theme → Blueprint → Screen generation
89,993 LOC → 1,526 LOC (98.3% reduction)
This package replaces 14 bloated packages with a single, focused implementation of the core pipeline.
Transform JSON screen definitions into production-ready React components with multiple CSS frameworks.
Features:
Quick Start:
import {
validateScreenDefinition,
resolveScreen,
generateReactComponent,
} from '@tekton/core/screen-generation';
const validation = validateScreenDefinition(screenDef);
const resolved = await resolveScreen(screenDef);
const result = generateReactComponent(resolved);
📚 Documentation:
Advanced responsive design system with xl/2xl breakpoints, Container Queries, and Orientation support.
Features:
Quick Start:
import {
generateResponsiveCSS,
generateContainerQueryCSS,
generateOrientationCSS,
} from '@tekton/core/layout-tokens';
// Responsive breakpoints including xl/2xl
const responsive = generateResponsiveCSS({
default: { gridColumns: 1 },
md: { gridColumns: 2 },
xl: { gridColumns: 4 },
'2xl': { gridColumns: 6 },
});
// Container Queries for component-level responsiveness
const container = generateContainerQueryCSS({
name: 'card-grid',
type: 'inline-size',
breakpoints: {
md: { minWidth: 480, css: { 'grid-template-columns': 'repeat(2, 1fr)' } },
lg: { minWidth: 640, css: { 'grid-template-columns': 'repeat(3, 1fr)' } },
},
});
// Orientation support for tablets
const orientation = generateOrientationCSS({
portrait: { gridColumns: 1 },
landscape: { gridColumns: 2 },
});
📚 Documentation:
pnpm add @tekton/core
import { loadTheme, createBlueprint, render } from '@tekton/core';
// 1. Load theme
const theme = loadTheme('calm-wellness');
// 2. Create blueprint
const blueprint = createBlueprint({
name: 'Dashboard',
themeId: theme.id,
layout: 'dashboard',
components: [
{ type: 'Heading', props: { level: 1 }, children: ['Welcome'] },
{
type: 'Card',
children: [
{ type: 'Text', children: ['Your stats here'] },
{ type: 'Button', props: { variant: 'primary' }, children: ['View More'] },
],
},
],
});
// 3. Render to JSX
const result = render(blueprint);
console.log(result.code);
Professional design token architecture with atomic, semantic, and component layers:
import type { ThemeWithTokens } from '@tekton/core';
import { resolveToken, generateThemeCSS } from '@tekton/core';
// Define theme with 3-layer token structure
const theme: ThemeWithTokens = {
id: 'my-theme',
name: 'My Theme',
tokens: {
// Layer 1: Atomic Tokens (raw values)
atomic: {
color: {
blue: { '500': '#3b82f6', '600': '#2563eb' },
neutral: { '50': '#f9fafb', '900': '#111827' },
},
spacing: { '4': '16px', '8': '32px' },
radius: { md: '8px' },
},
// Layer 2: Semantic Tokens (meaning-based)
semantic: {
background: {
page: 'atomic.color.neutral.50',
surface: '#ffffff',
},
foreground: {
primary: 'atomic.color.neutral.900',
accent: 'atomic.color.blue.500',
},
},
// Layer 3: Component Tokens (component-specific)
component: {
button: {
primary: {
background: 'semantic.foreground.accent',
foreground: '#ffffff',
hover: { background: 'atomic.color.blue.600' },
},
},
},
},
};
// Resolve token with automatic reference resolution
const color = resolveToken('component.button.primary.background', theme.tokens);
// → '#3b82f6' (semantic.foreground.accent → atomic.color.blue.500)
// Generate CSS Variables
const css = generateThemeCSS(theme);
// Outputs:
// :root {
// --color-blue-500: #3b82f6;
// --background-page: #f9fafb;
// --button-primary-background: #3b82f6;
// }
Key Features:
import { resolveToken, resolveWithFallback } from '@tekton/core';
// Simple resolution
resolveToken('atomic.color.blue.500', tokens);
// → '#3b82f6'
// Multi-level resolution
resolveToken('component.button.primary.background', tokens);
// → '#3b82f6' (resolves through semantic layer)
// Fallback chain (most specific to least specific)
resolveWithFallback(
'component.button.custom.background', // Try component first
'semantic.foreground.accent', // Fallback to semantic
'atomic.color.blue.500', // Final fallback to atomic
tokens
);
const theme: ThemeWithTokens = {
// ... base theme ...
darkMode: {
tokens: {
semantic: {
background: {
page: 'atomic.color.neutral.900',
surface: 'atomic.color.neutral.800',
},
},
component: {
button: {
primary: {
background: 'atomic.color.blue.400',
},
},
},
},
},
};
// Generate CSS with dark mode
const css = generateThemeCSS(theme);
// Outputs:
// :root { /* light mode variables */ }
// .dark { /* dark mode overrides */ }
import { validateTheme } from '@tekton/core';
const result = validateTheme(myTheme);
if (!result.valid) {
console.error('Validation errors:', result.errors);
// → ['tokens.atomic.color: Required', 'tokens.semantic.background.page: Required']
}
// Type definitions
import type { AtomicTokens, SemanticTokens, ComponentTokens, ThemeWithTokens } from '@tekton/core';
// Token resolution
import { resolveToken, resolveWithFallback } from '@tekton/core';
// CSS generation
import { generateThemeCSS } from '@tekton/core';
// Validation
import { validateTheme } from '@tekton/core';
resolveToken(ref, tokens)Resolves a token reference to its final value with multi-level resolution.
Parameters:
ref: string - Token reference in dot notation (e.g., 'atomic.color.blue.500')tokens: ThemeWithTokens['tokens'] - Theme token structureReturns: string - Resolved token value
Throws:
Error - If token not foundError - If circular reference detectedExamples:
// Direct atomic token
resolveToken('atomic.color.blue.500', tokens);
// → '#3b82f6'
// Semantic token (references atomic)
resolveToken('semantic.background.page', tokens);
// → '#f9fafb' (via atomic.color.neutral.50)
// Component token (multi-level resolution)
resolveToken('component.button.primary.background', tokens);
// → '#3b82f6' (semantic.foreground.accent → atomic.color.blue.500)
// Direct value (returned as-is)
resolveToken('#3b82f6', tokens);
// → '#3b82f6'
resolveWithFallback(componentRef, semanticRef, atomicRef, tokens)Resolves token with graceful fallback: Component → Semantic → Atomic.
Parameters:
componentRef: string - Component-level token referencesemanticRef: string - Semantic-level token reference (fallback)atomicRef: string - Atomic-level token reference (final fallback)tokens: ThemeWithTokens['tokens'] - Theme token structureReturns: string - Resolved value from first successful resolution
Throws: Error - If all fallback attempts fail
Example:
resolveWithFallback(
'component.button.custom.background', // Missing (skipped)
'semantic.foreground.accent', // Exists → returns '#3b82f6'
'atomic.color.blue.500', // Not evaluated
tokens
);
generateThemeCSS(theme)Generates complete CSS with CSS Variables from theme tokens.
Parameters:
theme: ThemeWithTokens - Theme with 3-layer token structureReturns: string - Generated CSS with :root and .dark selectors
Example:
const css = generateThemeCSS(theme);
// Output structure:
// :root {
// /* Layer 1: Atomic Tokens */
// --color-blue-500: #3b82f6;
// --spacing-4: 16px;
//
// /* Layer 2: Semantic Tokens */
// --background-page: #f9fafb;
// --foreground-accent: #3b82f6;
//
// /* Layer 3: Component Tokens */
// --button-primary-background: #3b82f6;
// --button-primary-hover-background: #2563eb;
// }
//
// .dark {
// --background-page: #111827;
// }
validateTheme(theme)Validates theme with token structure using Zod schemas.
Parameters:
theme: unknown - Theme object to validateReturns: ValidationResult
interface ValidationResult {
valid: boolean;
errors?: string[]; // Present if valid is false
}
Example:
const result = validateTheme(myTheme);
if (result.valid) {
console.log('✅ Theme is valid');
} else {
console.error('❌ Validation failed:');
result.errors?.forEach(err => console.error(` - ${err}`));
}
// Load theme by ID
const theme = loadTheme('calm-wellness');
// List all available themes
const themes = listThemes();
// Check if theme is built-in
const isBuiltin = isBuiltinTheme('calm-wellness'); // true
// Generate CSS variables from theme
const cssVars = generateCSSVariables(theme);
// Convert OKLCH to CSS
const css = oklchToCSS({ l: 0.7, c: 0.1, h: 170 }); // 'oklch(0.7 0.1 170)'
// Create blueprint
const blueprint = createBlueprint({
name: 'Page Name',
description: 'Optional description',
themeId: 'calm-wellness',
layout: 'single-column', // or 'two-column', 'sidebar-left', 'dashboard', 'landing'
components: [{ type: 'Button', children: ['Click'] }],
});
// Validate blueprint
const validation = validateBlueprint(blueprint);
if (!validation.valid) {
console.error(validation.errors);
}
// Check component validity
isValidComponent('Button'); // true
isValidComponent('FakeComponent'); // false
// Get layout slots
const slots = getLayoutSlots('dashboard');
// [{ name: 'header', required: true }, { name: 'sidebar', required: true }, ...]
// Render blueprint to JSX
const result = render(blueprint);
if (result.success) {
console.log(result.code);
}
// Render with theme CSS variables included
const resultWithTheme = renderWithTheme(blueprint);
// Render options
const result = render(blueprint, {
typescript: true, // Generate TypeScript (default: true)
indent: 2, // Indentation spaces (default: 2)
semicolons: true, // Include semicolons (default: true)
});
// Quick render single component
const jsx = renderSingleComponent({ type: 'Button', children: ['Click'] });
// Render multiple components without layout
const jsx = renderComponents([
{ type: 'Heading', children: ['Title'] },
{ type: 'Text', children: ['Content'] },
]);
The token system generates CSS Variables with a consistent naming pattern:
--color-{palette}-{shade}: {value}
--spacing-{size}: {value}
--radius-{size}: {value}
--typography-{name}-size: {value}
--typography-{name}-line-height: {value}
--typography-{name}-weight: {value}
--shadow-{name}: {value}
--transition-{name}: {value}
Examples:
--color-blue-500: #3b82f6;
--color-neutral-50: #f9fafb;
--spacing-4: 16px;
--radius-md: 8px;
--typography-body-size: 16px;
--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
--{category}-{name}: {value}
Examples:
--background-page: #f9fafb;
--foreground-primary: #111827;
--border-default: #e5e7eb;
--surface-primary: #ffffff;
--{component}-{variant}-{property}: {value}
--{component}-{variant}-{state}-{property}: {value}
Examples:
/* Button primary variant */
--button-primary-background: #3b82f6;
--button-primary-foreground: #ffffff;
--button-primary-hover-background: #2563eb;
--button-primary-disabled-foreground: #9ca3af;
/* Input component */
--input-background: #ffffff;
--input-border: #e5e7eb;
--input-focus-ring: #3b82f6;
--input-error-border: #ef4444;
Dark mode uses the same variable names but scoped to .dark class:
.dark {
--background-page: #111827;
--foreground-primary: #f9fafb;
--button-primary-background: #60a5fa;
}
Usage in Components:
.button-primary {
background: var(--button-primary-background);
color: var(--button-primary-foreground);
border-radius: var(--radius-md);
padding: var(--spacing-4);
}
.button-primary:hover {
background: var(--button-primary-hover-background);
}
.button-primary:disabled {
background: var(--button-primary-disabled-background);
color: var(--button-primary-disabled-foreground);
}
Before (0.1.0):
const theme = loadTheme('calm-wellness');
const cssVars = generateCSSVariables(theme);
After (0.2.0 with Token System):
import type { ThemeWithTokens } from '@tekton/core';
import { generateThemeCSS } from '@tekton/core';
// Old themes still work (backward compatible)
const theme = loadTheme('calm-wellness');
// New: Extend with token system
const themeWithTokens: ThemeWithTokens = {
...theme,
tokens: {
atomic: {
/* ... */
},
semantic: {
/* ... */
},
component: {
/* ... */
},
},
};
const css = generateThemeCSS(themeWithTokens);
ThemeWithTokens interfacevalidateTheme()generateThemeCSS() replaces generateCSSVariables()darkMode propertyNone - the token system is an additive feature in 0.2.0.
| Layout | Slots |
|---|---|
single-column | header?, main, footer? |
two-column | header?, left, right, footer? |
sidebar-left | header?, sidebar, main, footer? |
sidebar-right | header?, main, sidebar, footer? |
dashboard | header, sidebar, main, footer? |
landing | hero, features?, cta?, footer? |
Button, Input, Card, Text, Heading, Image, Link, List, Form, Modal, Tabs, Table, Badge, Avatar, Dropdown, Checkbox, Radio, Switch, Slider, Progress
calm-wellness - Soft, meditative atmospheredynamic-fitness - Energetic, bold designkorean-fintech - Clean, trustworthy financemedia-streaming - Dark, immersive entertainmentpremium-editorial - Elegant, typography-focusedsaas-dashboard - Professional, data-richsaas-modern - Clean, modern SaaStech-startup - Bold, innovative techwarm-humanist - Friendly, approachable@tekton/core (1,526 LOC)
├── Core Pipeline (742 LOC)
│ ├── types.ts (94 LOC) - Core type definitions
│ ├── theme.ts (131 LOC) - Theme loading & CSS generation
│ ├── blueprint.ts (169 LOC) - Blueprint creation & validation
│ ├── render.ts (297 LOC) - Template-based JSX generation
│ └── index.ts (51 LOC) - Public API exports
│
└── Token System (784 LOC) [NEW in 0.2.0]
├── tokens.ts (189 LOC) - 3-layer token type definitions
├── token-resolver.ts (146 LOC) - Token resolution & fallback logic
├── token-validation.ts (176 LOC) - Zod schema validation
└── css-generator.ts (273 LOC) - CSS Variables generation
3-Layer Token Architecture:
Benefits:
Template-based rendering (not AST-based):
What was removed:
pnpm test # Run tests
pnpm test:watch # Watch mode
pnpm test:coverage # Coverage report
Current: 132 tests, 96.37% coverage
| Module | Tests | Coverage |
|---|---|---|
| Token Types | 28 | 100% |
| Token Resolution | 35 | 98.5% |
| Token Validation | 32 | 97.2% |
| CSS Generation | 37 | 95.8% |
| Core Pipeline | - | 83% |
Token system is highly optimized for production use:
Benchmarked on Node.js 20, Apple M1.
MIT
FAQs
Core design system pipeline: Theme -> Blueprint -> Screen (~800 LOC)
The npm package @tekton-ui/core receives a total of 1 weekly downloads. As such, @tekton-ui/core popularity was classified as not popular.
We found that @tekton-ui/core demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.