@tokis/tokens 1.0.0 → 1.1.0

package/README.md

@@ -1,14 +1,14 @@
-# /tokens
+# @tokis/tokens
 
 Design token engine for the Tokis design system — color primitives, semantic scales, spacing, typography, shadows, motion, and CSS variable generation.
 
 ## Installation
 
 ```bash
-npm install /tokens
+npm install @tokis/tokens
 ```
 
-> Or install everything at once: `npm install tokis`
+> Or install everything at once: `npm install @tokis/tokis`
 
 ## Usage
 
@@ -25,7 +25,7 @@ import {
   lightTheme,
   darkTheme,
   generateCSSVars,
-} from '/tokens';
+} from '@tokis/tokens';
 
 // Generate CSS custom properties from a theme
 const css = generateCSSVars(lightTheme);
@@ -34,7 +34,7 @@ const css = generateCSSVars(lightTheme);
 ### CSS
 
 ```css
-@import '/tokens/css';
+@import '@tokis/tokens/css';
 ```
 
 ## What's Included

package/dist/cjs/css/generate-css-vars.js

@@ -1,50 +1,253 @@
 "use strict";
+/**
+ * Tokis CSS variable generator.
+ *
+ * Converts TypeScript primitive token objects into valid CSS custom property
+ * declarations. This module serves two purposes:
+ *
+ *  1. **Build time** — `scripts/generate-tokens-css.ts` calls
+ *     `generateAllCssVars()` and writes the output to
+ *     `packages/theme/src/base/variables.css`, keeping CSS and TypeScript
+ *     in perfect sync. Run with: `pnpm tokens:generate`.
+ *
+ *  2. **Runtime injection** (escape hatch for CSS-in-JS contexts) — call
+ *     `generateAllCssVars()` and inject via a `<style>` tag. Not recommended
+ *     for production; prefer the precompiled static CSS.
+ *
+ * Generated variable names exactly match those referenced in
+ * `packages/theme/src/base/variables.css` and all component CSS files.
+ *
+ * Zero dependencies — plain TypeScript, no React, no DOM.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLightCssVars = generateLightCssVars;
+exports.generateDarkCssVars = generateDarkCssVars;
+exports.generateAllCssVars = generateAllCssVars;
 exports.generateCssVariables = generateCssVariables;
 const colors_js_1 = require("../primitives/colors");
 const spacing_js_1 = require("../primitives/spacing");
-const radius_js_1 = require("../primitives/radius");
 const typography_js_1 = require("../primitives/typography");
+const radius_js_1 = require("../primitives/radius");
 const shadows_js_1 = require("../primitives/shadows");
 const motion_js_1 = require("../primitives/motion");
 const zIndex_js_1 = require("../primitives/zIndex");
 const breakpoints_js_1 = require("../primitives/breakpoints");
-const color_js_1 = require("../semantic/color");
-const surface_js_1 = require("../semantic/surface");
-const text_js_1 = require("../semantic/text");
-const border_js_1 = require("../semantic/border");
-function generateCssVariables(scope = ':root') {
-    const vars = [];
-    const prefix = '--tokis-';
-    const add = (name, value) => {
-        vars.push(`  ${prefix}${name}: ${String(value)};`);
-    };
-    // Primitive: Colors
-    Object.entries(colors_js_1.colors).forEach(([key, value]) => add(`color-${key}`, value));
-    // Primitive: Spacing
-    Object.entries(spacing_js_1.spacing).forEach(([key, value]) => add(`spacing-${key}`, value));
-    // Primitive: Radius
-    Object.entries(radius_js_1.radius).forEach(([key, value]) => add(`radius-${key}`, value));
-    // Primitive: Typography
-    Object.entries(typography_js_1.typography.fontSize).forEach(([key, value]) => add(`font-size-${key}`, value));
-    Object.entries(typography_js_1.typography.fontWeight).forEach(([key, value]) => add(`font-weight-${key}`, String(value)));
-    add('font-family', typography_js_1.typography.fontFamily);
-    // Primitive: Shadows
-    Object.entries(shadows_js_1.shadows).forEach(([key, value]) => add(`shadow-${key}`, value));
-    // Primitive: Motion
-    Object.entries(motion_js_1.motion.duration).forEach(([key, value]) => add(`motion-duration-${key}`, value));
-    Object.entries(motion_js_1.motion.easing).forEach(([key, value]) => add(`motion-easing-${key}`, value));
-    // Primitive: Z-Index
-    Object.entries(zIndex_js_1.zIndex).forEach(([key, value]) => add(`z-index-${key}`, String(value)));
-    // Primitive: Breakpoints
-    Object.entries(breakpoints_js_1.breakpoints).forEach(([key, value]) => add(`breakpoint-${key}`, value));
-    // Semantic: Colors
-    Object.entries(color_js_1.semanticColors).forEach(([key, value]) => add(`semantic-color-${key}`, value));
-    // Semantic: Surface
-    Object.entries(surface_js_1.surface).forEach(([key, value]) => add(`surface-${key}`, value));
-    // Semantic: Text
-    Object.entries(text_js_1.text).forEach(([key, value]) => add(`text-${key}`, value));
-    // Semantic: Border
-    Object.entries(border_js_1.border).forEach(([key, value]) => add(`border-${key}`, value));
-    return `${scope} {\n${vars.join('\n')}\n}`;
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/** camelCase → kebab-case: `primaryHover` → `primary-hover` */
+function kebab(str) {
+    return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+/** Indent every line of a multi-line string. */
+function indent(str, spaces = 2) {
+    const pad = ' '.repeat(spaces);
+    return str
+        .split('\n')
+        .map((l) => (l.trim() ? `${pad}${l}` : ''))
+        .join('\n');
+}
+// ─── Light / :root block ─────────────────────────────────────────────────────
+function generateLightCssVars() {
+    const lines = [];
+    const v = (name, value) => `--tokis-${name}: ${String(value)};`;
+    // ── Primitive colors ──────────────────────────────────────────────────
+    lines.push('/* Primitive Colors */');
+    for (const [key, value] of Object.entries(colors_js_1.colors)) {
+        lines.push(v(`color-${kebab(key)}`, value));
+    }
+    // Legacy flat text-* aliases that component CSS files reference directly
+    // (e.g. `--tokis-text-primary`) — kept for backward compat with theme CSS.
+    lines.push('');
+    lines.push('/* Text — legacy flat aliases */');
+    lines.push(v('text-primary', colors_js_1.colors.textPrimary));
+    lines.push(v('text-secondary', colors_js_1.colors.textSecondary));
+    lines.push(v('text-tertiary', colors_js_1.colors.textTertiary));
+    lines.push(v('text-disabled', colors_js_1.colors.textDisabled));
+    lines.push(v('text-inverse', colors_js_1.colors.textInverse));
+    lines.push(v('text-on-primary', colors_js_1.colors.textOnPrimary));
+    lines.push(v('text-link', colors_js_1.colors.textLink));
+    lines.push(v('text-error', colors_js_1.colors.textError));
+    lines.push(v('text-success', colors_js_1.colors.textSuccess));
+    lines.push(v('text-warning', colors_js_1.colors.textWarning));
+    // ── Spacing ───────────────────────────────────────────────────────────
+    lines.push('');
+    lines.push('/* Spacing */');
+    for (const [key, value] of Object.entries(spacing_js_1.spacing)) {
+        if (!isNaN(Number(key))) {
+            lines.push(v(`spacing-${key}`, value));
+        }
+    }
+    // ── Typography ────────────────────────────────────────────────────────
+    lines.push('');
+    lines.push('/* Typography */');
+    lines.push(v('font-family', typography_js_1.typography.fontFamily.sans));
+    lines.push(v('font-family-mono', typography_js_1.typography.fontFamily.mono));
+    for (const [key, value] of Object.entries(typography_js_1.typography.fontSize)) {
+        lines.push(v(`font-size-${key}`, value));
+    }
+    for (const [key, value] of Object.entries(typography_js_1.typography.fontWeight)) {
+        if (key !== 'normal')
+            lines.push(v(`font-weight-${key}`, value));
+    }
+    for (const [key, value] of Object.entries(typography_js_1.typography.lineHeight)) {
+        lines.push(v(`line-height-${key}`, value));
+    }
+    for (const [key, value] of Object.entries(typography_js_1.typography.letterSpacing)) {
+        lines.push(v(`letter-spacing-${kebab(key)}`, value));
+    }
+    // ── Border Radius ─────────────────────────────────────────────────────
+    lines.push('');
+    lines.push('/* Border Radius */');
+    for (const [key, value] of Object.entries(radius_js_1.radius)) {
+        lines.push(v(`radius-${key}`, value));
+    }
+    // ── Shadows ───────────────────────────────────────────────────────────
+    lines.push('');
+    lines.push('/* Shadows */');
+    for (const [key, value] of Object.entries(shadows_js_1.shadows)) {
+        lines.push(v(`shadow-${key}`, value));
+    }
+    // ── Focus ─────────────────────────────────────────────────────────────
+    lines.push('');
+    lines.push('/* Focus */');
+    lines.push(v('color-focus-ring', colors_js_1.colors.focusRing));
+    lines.push(v('color-focus-ring-error', colors_js_1.colors.focusRingError));
+    // ── Surface interaction states ────────────────────────────────────────
+    lines.push('');
+    lines.push('/* Surface interaction states */');
+    lines.push(v('color-surface-hover', colors_js_1.colors.surfaceHover));
+    lines.push(v('color-surface-active', colors_js_1.colors.surfaceActive));
+    // ── Motion ────────────────────────────────────────────────────────────
+    lines.push('');
+    lines.push('/* Motion */');
+    for (const [key, value] of Object.entries(motion_js_1.motion.duration)) {
+        lines.push(v(`duration-${key}`, value));
+    }
+    for (const [key, value] of Object.entries(motion_js_1.motion.easing)) {
+        lines.push(v(`ease-${kebab(key)}`, value));
+    }
+    // ── Z-index ───────────────────────────────────────────────────────────
+    lines.push('');
+    lines.push('/* Z-index */');
+    for (const [key, value] of Object.entries(zIndex_js_1.zIndex)) {
+        lines.push(v(`z-${key}`, value));
+    }
+    // ── Breakpoints ───────────────────────────────────────────────────────
+    lines.push('');
+    lines.push('/* Breakpoints (JS reference — not usable in @media queries) */');
+    for (const [key, value] of Object.entries(breakpoints_js_1.breakpoints)) {
+        lines.push(v(`breakpoint-${key}`, value));
+    }
+    return `:root {\n${indent(lines.join('\n'))}\n}`;
+}
+// ─── Dark theme overrides ────────────────────────────────────────────────────
+/**
+ * Returns only the CSS custom properties that change in dark mode.
+ * Spacing, typography, radius, motion, and z-index are theme-invariant.
+ */
+function generateDarkCssVars() {
+    const dark = `\
+/* Brand */
+--tokis-color-primary:          #3b82f6;
+--tokis-color-primary-hover:    #60a5fa;
+--tokis-color-primary-active:   #93c5fd;
+--tokis-color-primary-subtle:   #1e3a5f;
+--tokis-color-secondary:        #a78bfa;
+--tokis-color-secondary-hover:  #c4b5fd;
+--tokis-color-secondary-subtle: #2e1065;
+
+/* Backgrounds & Surfaces */
+--tokis-color-background:       #0f172a;
+--tokis-color-surface:          #1e293b;
+--tokis-color-surface-raised:   #293548;
+--tokis-color-surface-overlay:  #1e293b;
+--tokis-color-surface-hover:    #334155;
+--tokis-color-surface-active:   #475569;
+
+/* Borders */
+--tokis-color-border:        #334155;
+--tokis-color-border-strong: #475569;
+
+/* Status */
+--tokis-color-error:           #f87171;
+--tokis-color-error-subtle:    #450a0a;
+--tokis-color-warning:         #fbbf24;
+--tokis-color-warning-subtle:  #451a03;
+--tokis-color-success:         #4ade80;
+--tokis-color-success-subtle:  #052e16;
+--tokis-color-info:            #38bdf8;
+--tokis-color-info-subtle:     #082f49;
+
+/* Text */
+--tokis-text-primary:          #f1f5f9;
+--tokis-text-secondary:        #94a3b8;
+--tokis-text-tertiary:         #64748b;
+--tokis-text-disabled:         #475569;
+--tokis-text-inverse:          #0f172a;
+--tokis-text-on-primary:       #ffffff;
+--tokis-text-link:             #60a5fa;
+--tokis-text-error:            #f87171;
+--tokis-text-success:          #4ade80;
+--tokis-text-warning:          #fbbf24;
+
+/* Neutral scale (inverted for dark) */
+--tokis-color-neutral-50:  #0f172a;
+--tokis-color-neutral-100: #1e293b;
+--tokis-color-neutral-200: #334155;
+--tokis-color-neutral-300: #475569;
+--tokis-color-neutral-400: #64748b;
+--tokis-color-neutral-500: #94a3b8;
+--tokis-color-neutral-600: #cbd5e1;
+--tokis-color-neutral-700: #e2e8f0;
+--tokis-color-neutral-800: #f1f5f9;
+--tokis-color-neutral-900: #f8fafc;
+
+/* Shadows (higher opacity for dark backgrounds) */
+--tokis-shadow-xs:  0 1px 2px 0 rgb(0 0 0 / 0.30);
+--tokis-shadow-sm:  0 1px 3px 0 rgb(0 0 0 / 0.40), 0 1px 2px -1px rgb(0 0 0 / 0.40);
+--tokis-shadow-md:  0 4px 6px -1px rgb(0 0 0 / 0.40), 0 2px 4px -2px rgb(0 0 0 / 0.40);
+--tokis-shadow-lg:  0 10px 15px -3px rgb(0 0 0 / 0.40), 0 4px 6px -4px rgb(0 0 0 / 0.40);
+--tokis-shadow-xl:  0 20px 25px -5px rgb(0 0 0 / 0.40), 0 8px 10px -6px rgb(0 0 0 / 0.40);
+
+/* Focus rings */
+--tokis-color-focus-ring:       rgb(59 130 246 / 0.20);
+--tokis-color-focus-ring-error: rgb(248 113 113 / 0.20);`;
+    return `[data-theme="dark"] {\n${indent(dark)}\n}`;
+}
+// ─── Full stylesheet ──────────────────────────────────────────────────────────
+/**
+ * Returns the complete CSS variable stylesheet:
+ * the light `:root` block followed by dark `[data-theme="dark"]` overrides.
+ *
+ * **Build-time usage** (`scripts/generate-tokens-css.ts`):
+ * ```ts
+ * import { generateAllCssVars } from '@tokis/tokens';
+ * import { writeFileSync } from 'node:fs';
+ * writeFileSync(
+ *   'packages/theme/src/base/variables.css',
+ *   generateAllCssVars(),
+ * );
+ * ```
+ */
+function generateAllCssVars() {
+    return [
+        '/* ============================================================',
+        '   Tokis — Design Token CSS Variables',
+        '   Auto-generated by @tokis/tokens — generate-css-vars.ts',
+        '   Run `pnpm tokens:generate` to regenerate after editing tokens.',
+        '   ============================================================ */',
+        '',
+        generateLightCssVars(),
+        '',
+        '/* ── Dark Theme ──────────────────────────────────────────── */',
+        generateDarkCssVars(),
+        '',
+    ].join('\n');
+}
+// ─── Backward-compat export ───────────────────────────────────────────────────
+/**
+ * @deprecated Use `generateLightCssVars()` or `generateAllCssVars()` instead.
+ * The `scope` parameter is ignored; the selector is always `:root`.
+ */
+function generateCssVariables(_scope = ':root') {
+    return generateLightCssVars();
 }

package/dist/cjs/primitives/breakpoints.js

@@ -1,9 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.breakpoints = void 0;
+/**
+ * Tokis responsive breakpoints.
+ * These map to `--tokis-breakpoint-{key}` CSS custom properties (for JS reference)
+ * and should be used with `@media (min-width: ...)` in CSS files.
+ *
+ * Note: CSS custom properties cannot be used inside media query conditions,
+ * so the values here serve as the canonical reference — CSS files hardcode
+ * the same pixel values directly in `@media` rules.
+ */
 exports.breakpoints = {
     sm: '640px',
     md: '768px',
     lg: '1024px',
     xl: '1280px',
+    '2xl': '1536px',
 };

package/dist/cjs/primitives/colors.js

@@ -1,26 +1,74 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.colors = void 0;
+/**
+ * Tokis primitive color tokens — canonical source of truth.
+ * The CSS variable file `theme/src/base/variables.css` is generated from
+ * these definitions via `scripts/generate-tokens-css.ts`.
+ *
+ * All values are plain strings so the object is JSON-serializable.
+ */
 exports.colors = {
+    // ── Brand: Primary ────────────────────────────────────────────────────
     primary: '#0066ff',
-    secondary: '#ff6600',
+    primaryHover: '#0052cc',
+    primaryActive: '#003d99',
+    primarySubtle: '#e6f0ff',
+    // ── Brand: Secondary ──────────────────────────────────────────────────
+    secondary: '#7c3aed',
+    secondaryHover: '#6d28d9',
+    secondarySubtle: '#ede9fe',
+    // ── Backgrounds & Surfaces ────────────────────────────────────────────
     background: '#ffffff',
-    surface: '#f5f5f5',
-    error: '#d32f2f',
-    warning: '#f57c00',
-    success: '#388e3c',
-    neutral100: '#f5f5f5',
-    neutral200: '#eeeeee',
-    neutral300: '#e0e0e0',
-    neutral400: '#bdbdbd',
-    neutral500: '#9e9e9e',
-    neutral600: '#757575',
-    neutral700: '#616161',
-    neutral800: '#424242',
-    neutral900: '#212121',
+    surface: '#f8f9fa',
+    surfaceRaised: '#ffffff',
+    surfaceOverlay: '#ffffff',
+    surfaceHover: '#f1f5f9',
+    surfaceActive: '#e2e8f0',
+    // ── Borders ───────────────────────────────────────────────────────────
+    border: '#e2e8f0',
+    borderStrong: '#cbd5e1',
+    // ── Status: Error ─────────────────────────────────────────────────────
+    error: '#dc2626',
+    errorSubtle: '#fef2f2',
+    // ── Status: Warning ───────────────────────────────────────────────────
+    warning: '#d97706',
+    warningSubtle: '#fffbeb',
+    // ── Status: Success ───────────────────────────────────────────────────
+    success: '#16a34a',
+    successSubtle: '#f0fdf4',
+    // ── Status: Info ──────────────────────────────────────────────────────
+    info: '#0284c7',
+    infoSubtle: '#f0f9ff',
+    // ── Text ──────────────────────────────────────────────────────────────
+    textPrimary: '#0f172a',
+    textSecondary: '#475569',
+    textTertiary: '#94a3b8',
+    textDisabled: '#cbd5e1',
+    textInverse: '#ffffff',
+    textOnPrimary: '#ffffff',
+    textLink: '#0066ff',
+    textError: '#dc2626',
+    textSuccess: '#16a34a',
+    textWarning: '#d97706',
+    // ── Neutral scale (Slate) ─────────────────────────────────────────────
+    neutral50: '#f8fafc',
+    neutral100: '#f1f5f9',
+    neutral200: '#e2e8f0',
+    neutral300: '#cbd5e1',
+    neutral400: '#94a3b8',
+    neutral500: '#64748b',
+    neutral600: '#475569',
+    neutral700: '#334155',
+    neutral800: '#1e293b',
+    neutral900: '#0f172a',
+    // ── On-color ──────────────────────────────────────────────────────────
     onPrimary: '#ffffff',
     onSecondary: '#ffffff',
-    onBackground: '#212121',
-    onSurface: '#424242',
+    onBackground: '#0f172a',
+    onSurface: '#475569',
     onError: '#ffffff',
+    // ── Focus ─────────────────────────────────────────────────────────────
+    focusRing: 'rgb(0 102 255 / 0.15)',
+    focusRingError: 'rgb(220 38 38 / 0.15)',
 };

package/dist/cjs/primitives/motion.js

@@ -1,13 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.motion = void 0;
+/**
+ * Tokis motion tokens — durations and easing functions.
+ * These map to `--tokis-duration-{key}` and `--tokis-ease-{key}` CSS variables.
+ *
+ * Always reference via CSS variables rather than importing at runtime to
+ * preserve zero-runtime guarantee.
+ */
 exports.motion = {
+    // ── Durations ─────────────────────────────────────────────────────────
     duration: {
-        fast: '150ms',
-        normal: '300ms',
-        slow: '500ms',
+        fast: '100ms', // micro-interactions (hover, focus ring)
+        normal: '200ms', // most transitions (color, opacity)
+        slow: '300ms', // larger state changes (dropdown, tooltip)
+        slower: '500ms', // complex animations (page-level, charts)
     },
+    // ── Easing curves ─────────────────────────────────────────────────────
     easing: {
+        easeIn: 'cubic-bezier(0.4, 0, 1, 1)',
+        easeOut: 'cubic-bezier(0, 0, 0.2, 1)',
         easeInOut: 'cubic-bezier(0.4, 0, 0.2, 1)',
+        spring: 'cubic-bezier(0.175, 0.885, 0.32, 1.275)',
     },
 };

package/dist/cjs/primitives/radius.js

@@ -1,10 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.radius = void 0;
+/**
+ * Tokis border-radius tokens.
+ * These map to `--tokis-radius-{key}` CSS variables.
+ */
 exports.radius = {
     none: '0px',
-    sm: '2px',
-    md: '4px',
+    xs: '2px',
+    sm: '4px',
+    md: '6px',
     lg: '8px',
+    xl: '12px',
+    '2xl': '16px',
     full: '9999px',
 };

package/dist/cjs/primitives/shadows.js

@@ -1,8 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.shadows = void 0;
+/**
+ * Tokis box-shadow tokens.
+ * These map to `--tokis-shadow-{key}` CSS variables.
+ * All shadows use modern `rgb()` with `/` alpha syntax for correct rendering.
+ */
 exports.shadows = {
-    sm: '0 1px 2px rgba(0,0,0,0.05)',
-    md: '0 4px 6px rgba(0,0,0,0.1)',
-    lg: '0 10px 15px rgba(0,0,0,0.15)',
+    xs: '0 1px 2px 0 rgb(0 0 0 / 0.05)',
+    sm: '0 1px 3px 0 rgb(0 0 0 / 0.10), 0 1px 2px -1px rgb(0 0 0 / 0.10)',
+    md: '0 4px 6px -1px rgb(0 0 0 / 0.10), 0 2px 4px -2px rgb(0 0 0 / 0.10)',
+    lg: '0 10px 15px -3px rgb(0 0 0 / 0.10), 0 4px 6px -4px rgb(0 0 0 / 0.10)',
+    xl: '0 20px 25px -5px rgb(0 0 0 / 0.10), 0 8px 10px -6px rgb(0 0 0 / 0.10)',
+    '2xl': '0 25px 50px -12px rgb(0 0 0 / 0.25)',
+    inner: 'inset 0 2px 4px 0 rgb(0 0 0 / 0.05)',
 };

package/dist/cjs/primitives/spacing.js

@@ -1,10 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.spacing = void 0;
+/**
+ * Tokis spacing tokens.
+ * Uses a 4px base unit with numeric keys that map directly to
+ * `--tokis-spacing-{key}` CSS variables (e.g. `spacing[4]` → `--tokis-spacing-4`).
+ *
+ * Named aliases (xs/sm/md/lg/xl) are preserved for backward compatibility
+ * but numeric keys are the preferred form in component code.
+ */
 exports.spacing = {
+    // ── Numeric scale (4 px base) ─────────────────────────────────────────
+    0: '0px',
+    1: '4px',
+    2: '8px',
+    3: '12px',
+    4: '16px',
+    5: '20px',
+    6: '24px',
+    8: '32px',
+    10: '40px',
+    12: '48px',
+    16: '64px',
+    20: '80px',
+    24: '96px',
+    // ── Named aliases (legacy / semantic) ────────────────────────────────
+    /** @deprecated Use numeric key `1` → 4px */
     xs: '4px',
+    /** @deprecated Use numeric key `2` → 8px */
     sm: '8px',
+    /** @deprecated Use numeric key `4` → 16px */
     md: '16px',
+    /** @deprecated Use numeric key `6` → 24px */
     lg: '24px',
+    /** @deprecated Use numeric key `8` → 32px */
     xl: '32px',
 };

package/dist/cjs/primitives/typography.js

@@ -1,18 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.typography = void 0;
+/**
+ * Tokis typography tokens.
+ * These map to `--tokis-font-*` CSS variables.
+ */
 exports.typography = {
-    fontFamily: 'system-ui, sans-serif',
+    // ── Font families ─────────────────────────────────────────────────────
+    fontFamily: {
+        sans: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Inter', Helvetica, Arial, sans-serif",
+        mono: "'SF Mono', 'Fira Code', 'Cascadia Code', Consolas, monospace",
+    },
+    // ── Font sizes ────────────────────────────────────────────────────────
     fontSize: {
-        xs: '0.75rem',
-        sm: '0.875rem',
-        md: '1rem',
-        lg: '1.125rem',
-        xl: '1.25rem',
+        xs: '0.75rem', // 12px
+        sm: '0.875rem', // 14px
+        md: '1rem', // 16px
+        lg: '1.125rem', // 18px
+        xl: '1.25rem', // 20px
+        '2xl': '1.5rem', // 24px
+        '3xl': '1.875rem', // 30px
+        '4xl': '2.25rem', // 36px
     },
+    // ── Font weights ──────────────────────────────────────────────────────
     fontWeight: {
-        normal: 400,
+        regular: 400,
         medium: 500,
+        semibold: 600,
         bold: 700,
+        /** @deprecated Use `semibold` (600) or `bold` (700) */
+        normal: 400,
+    },
+    // ── Line heights ──────────────────────────────────────────────────────
+    lineHeight: {
+        tight: 1.25,
+        normal: 1.5,
+        relaxed: 1.75,
+    },
+    // ── Letter spacing ────────────────────────────────────────────────────
+    letterSpacing: {
+        tight: '-0.025em',
+        normal: '0em',
+        wide: '0.025em',
     },
 };

package/dist/cjs/primitives/zIndex.js

@@ -1,8 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.zIndex = void 0;
+/**
+ * Tokis z-index tokens — layering scale.
+ * These map to `--tokis-z-{key}` CSS variables.
+ *
+ * Layers are ordered by increasing elevation. Each layer is intentionally
+ * spaced to allow insertion of custom layers without breaking the scale.
+ */
 exports.zIndex = {
+    base: 0,
+    raised: 1,
     dropdown: 1000,
-    modal: 2000,
-    tooltip: 3000,
+    sticky: 1100,
+    overlay: 1200,
+    modal: 1300,
+    popover: 1400,
+    tooltip: 1500,
+    toast: 1600,
 };