@talelk/newui-tokens 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talelk/newui-tokens",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Framework-neutral design tokens (colors, radius, typography, spacing, elevation, focus).",
   "exports": {

package/src/index.d.ts

@@ -33,6 +33,10 @@ export const radiusRoles: Record<
 >
 
 export const shadows: Record<string, string>
+export const shadowRoles: Record<
+  'card' | 'raised' | 'popover' | 'dialog' | 'toast' | 'drag',
+  string
+>
 
 export const focusRing: {
   light: Record<string, string>

package/src/index.js

@@ -27,11 +27,28 @@
  * none may be renamed or removed.
  */
 
-import colorsData from './tokens/colors.js'
+import exportedColors from './tokens/colors.js'
 import effectsData from './tokens/effects.js'
+import * as instrument from './tokens/instrument.js'
 import radiusTokens from './tokens/radius.js'
 import typographyTokens from './tokens/typography.js'
 
+// The Figma export stays untouched; the instrument-panel layer replaces ramp
+// steps on a copy, before anything resolves against them (ADR-0016).
+const colorsData = {
+  ...exportedColors,
+  lightMode: withRamps(exportedColors.lightMode, instrument.ramps.lightMode),
+  darkMode: withRamps(exportedColors.darkMode, instrument.ramps.darkMode),
+}
+
+function withRamps(palette, overrides) {
+  const out = { ...palette }
+  for (const [family, steps] of Object.entries(overrides)) {
+    out[family] = { ...palette[family], ...steps }
+  }
+  return out
+}
+
 // ---------- COLORS ----------
 
 /**
@@ -88,6 +105,23 @@ export const semanticColors = {
   dark: resolveThemedLayer(colorsData.themedVariables.dark),
 }
 
+// Mode-flipping scrim (alias layer — the generated `colors.js` stays
+// untouched). One `--surface-scrim` runtime var replaces every hand-copied
+// `bg-black-overlay-200 dark:bg-black-overlay-700` backdrop pair, so overlays
+// name the role and the theme flip lives here, never in a `dark:` variant.
+semanticColors.light.surface.scrim = colorsData.overlay.black[200]
+semanticColors.dark.surface.scrim = colorsData.overlay.black[700]
+
+// Instrument-panel semantic entries: the Mist frame (`surface-canvas`) behind
+// sheets, shared by the sidebar.
+for (const theme of ['light', 'dark']) {
+  for (const [category, entries] of Object.entries(
+    instrument.semantic[theme],
+  )) {
+    Object.assign(semanticColors[theme][category], entries)
+  }
+}
+
 // ---------- RADIUS ----------
 
 /**
@@ -101,9 +135,9 @@ export const semanticColors = {
  * recipe independently.
  */
 export const radiusRoles = {
-  control: radiusTokens[3],
-  card: radiusTokens[4],
-  overlay: radiusTokens[6],
+  control: instrument.radiusRoles.control,
+  card: instrument.radiusRoles.card,
+  overlay: instrument.radiusRoles.overlay,
   pill: radiusTokens.full,
 }
 
@@ -120,10 +154,11 @@ export const radius = { ...radiusTokens, ...radiusRoles }
  * frappe-ui stylesheet can still paint the shadow. `plugin.js` reads the key
  * list from here and points each Tailwind key at its variable.
  *
- * Only the light steps ship. Espresso 2.0 references `elevation/light/*` on
- * its dark-mode page too, so `elevation.dark` in `effects.js` is not what
- * frappe-ui renders and is not exported. Focus is a separate shape, and a
- * different CSS property: see `focusRing`.
+ * This flat map carries the light steps (a consumer with no stylesheet picks
+ * a side itself); the runtime `--elevation-*` variables in `cssVariables`
+ * additionally ship `elevation.dark` under the dark selector, so a themed
+ * page gets dark-tuned depth. Focus is a separate shape, and a different CSS
+ * property: see `focusRing`.
  */
 export const shadows = buildShadows()
 
@@ -140,6 +175,21 @@ function buildShadows() {
   return { ...out, ...effectsData.elevation.custom }
 }
 
+/**
+ * Stable component roles mapped onto the primitive elevation steps, the
+ * shadow counterpart of `radiusRoles`. Components name the role
+ * (`shadow-popover`) so retuning a surface family's depth is one edit here,
+ * not a sweep of every recipe's step pick.
+ */
+export const shadowRoles = {
+  card: 'sm',
+  raised: 'base',
+  popover: 'md',
+  dialog: 'lg',
+  toast: 'xl',
+  drag: '2xl',
+}
+
 // Focus tokens arrive as single-layer `0 0 0 <spread> <color>` shadows.
 // Re-express as an `outline` shorthand so the focus ring never collides with
 // a `shadow-*` utility on the same element and survives forced-colors mode
@@ -168,8 +218,8 @@ function toOutlines(layer) {
  * dark ones 3px, which is why this one does mode-swap and `shadows` does not.
  */
 export const focusRing = {
-  light: toOutlines(effectsData.focus.light),
-  dark: toOutlines(effectsData.focus.dark),
+  light: toOutlines({ ...effectsData.focus.light, ...instrument.focus.light }),
+  dark: toOutlines({ ...effectsData.focus.dark, ...instrument.focus.dark }),
 }
 
 // ---------- TYPOGRAPHY ----------
@@ -191,7 +241,7 @@ export const fontSize = buildFontSize()
 function buildFontSize() {
   const out = {}
   for (const [key, [size, meta]] of Object.entries(typographyTokens.fontSize)) {
-    out[key] = { fontSize: size, ...meta }
+    out[key] = { fontSize: size, ...meta, ...instrument.fontSize[key] }
   }
   // Only these two. The paragraph family is the text family at a looser
   // line-height with its own tracking, and nothing else. Spreading the whole
@@ -203,6 +253,7 @@ function buildFontSize() {
       ...out[key],
       lineHeight: p.lineHeight,
       letterSpacing: p.letterSpacing,
+      ...instrument.fontSize[`p-${key}`],
     }
   }
   return out
@@ -215,13 +266,34 @@ function buildFontSize() {
  */
 export const fontWeight = typographyTokens.fontWeight
 
-export const fontFamily = typographyTokens.fontFamily
+export const fontFamily = {
+  ...typographyTokens.fontFamily,
+  ...instrument.fontFamily,
+}
 
 /**
  * Letter-spacing per (size, weight), for the `text` and `paragraph` families
  * separately. The only token property that varies by weight.
  */
-export const tracking = typographyTokens.tracking
+export const tracking = retrack(typographyTokens.tracking)
+
+// Plex wants the size's own tracking at every weight: the export's per-weight
+// spread was tuned for Inter.
+function retrack(table) {
+  const out = {}
+  for (const [group, sizes] of Object.entries(table)) {
+    out[group] = {}
+    for (const [size, weights] of Object.entries(sizes)) {
+      const key = group === 'paragraph' ? `p-${size}` : size
+      const value = instrument.trackingFor(key)
+      out[group][size] =
+        value === undefined
+          ? weights
+          : Object.fromEntries(Object.keys(weights).map((w) => [w, value]))
+    }
+  }
+  return out
+}
 
 // ---------- SIZING ----------
 
@@ -262,14 +334,25 @@ export const layoutSpacing = {
   'page-gutter': '1.5rem',
   'page-gutter-wide': '2rem',
   'page-stack': '2rem',
+  // Region roles codified from the values menus, dialogs, toolbars and data
+  // tables already repeat numerically, so density retunes in one place.
+  'menu-pad': '0.25rem',
+  'dialog-pad': '1rem',
+  'table-cell-x': '0.625rem',
+  'table-cell-y': '0.25rem',
+  'toolbar-pad': '0.5rem',
+  stack: '1rem',
+  inline: '0.5rem',
 }
 
 /** Breakpoint minimums. Not in the Figma export — decided in code. */
 export const screens = {
+  xs: '360px',
   sm: '640px',
   md: '768px',
   lg: '1024px',
   xl: '1280px',
+  '2xl': '1536px',
 }
 
 // ---------- CSS VARIABLES ----------
@@ -326,6 +409,12 @@ function effectVariables() {
   for (const [name, value] of Object.entries(effectsData.elevation.custom)) {
     light[`--elevation-${name}`] = value
   }
+  // Dark elevation ships: `--elevation-*` re-values under the dark selector
+  // (deeper ambient + key shadows, fainter inset highlight), so dark mode no
+  // longer renders the light shadow stack unchanged.
+  for (const [step, value] of Object.entries(effectsData.elevation.dark)) {
+    dark[`--elevation-${step}`] = value
+  }
   for (const [name, value] of Object.entries(focusRing.light)) {
     light[`--focus-outline-${name}`] = value
   }
@@ -351,12 +440,12 @@ function radiusVariables() {
  *   cssVariables.dark['--surface-base']
  *
  * `light` goes on `:root`, `dark` on `[data-theme="dark"]`. Neither is a
- * subset of the other. `dark` re-values the semantic and focus properties
- * that `light` already declares, and adds the dark ramps under their own
- * `--dark-*` names. Those are the only keys it has that `light` lacks.
- * `light` additionally carries the light ramps (`--gray-500`), elevation and
- * radius. None of those three flip by theme, so a property `dark` leaves out
- * keeps its `:root` value.
+ * subset of the other. `dark` re-values the semantic, elevation and focus
+ * properties that `light` already declares, and adds the dark ramps under
+ * their own `--dark-*` names. Those are the only keys it has that `light`
+ * lacks. `light` additionally carries the light ramps (`--gray-500`) and
+ * radius, which do not flip by theme, so a property `dark` leaves out keeps
+ * its `:root` value.
  *
  * `plugin.js` emits both into the base layer, which is how a frappe-ui page
  * gets them. Read this map directly when you need a token's value somewhere

package/src/tokens/instrument.js

@@ -0,0 +1,155 @@
+/**
+ * The instrument-panel layer: the hand-authored retune that sits on top of the
+ * Figma export (`colors.js`, `radius.js`, `typography.js` stay generated and
+ * untouched — see ADR-0016).
+ *
+ * The kit is for people who spend the day inside records: dense tables,
+ * filters, forms. This layer encodes that brief as data:
+ *
+ * - a cool gray family (Mist frame, white Sheet for data, Graphite ink, Pewter
+ *   secondary ink, Rule hairlines) instead of the export's near-neutral gray;
+ * - the `blue` theme retuned to Petrol — the kit's one accent: primary
+ *   actions, focus, the active row;
+ * - IBM Plex Sans (one variable family; its condensed width serves narrow
+ *   columns, its default figures are tabular, so numbers align in columns);
+ * - a type scale one step tighter (13px interface text) with no positive
+ *   tracking, which suited Inter and only loosens Plex;
+ * - radius by role: 4px controls, 6px sheets, 8px overlays.
+ *
+ * Every value is a replacement for a name that already exists, except
+ * `surface.canvas` (the frame behind sheets) — the token surface stays
+ * additive-only (ADR-0010).
+ */
+
+/** Ramp steps replaced in the exported palettes, per theme. */
+export const ramps = {
+  lightMode: {
+    gray: {
+      50: 'oklch(0.976 0.003 264.5)', // #F6F7F9
+      100: 'oklch(0.954 0.005 247.9)', // #EDF0F3 Mist
+      200: 'oklch(0.923 0.008 253.9)', // #E2E6EB
+      300: 'oklch(0.883 0.012 252.1)', // #D3D9E0 Rule
+      400: 'oklch(0.791 0.017 250.9)', // #B3BCC6
+      500: 'oklch(0.665 0.023 252.6)', // #8A95A2
+      600: 'oklch(0.612 0.025 254.5)', // #7A8593 muted tier, kept under AA
+      700: 'oklch(0.489 0.028 256.2)', // #566170 Pewter
+      800: 'oklch(0.364 0.024 255.7)', // #363F4B
+      900: 'oklch(0.241 0.024 256.4)', // #18202B Graphite
+      950: 'oklch(0.189 0.019 255.8)', // #0E141C
+    },
+    blue: {
+      50: 'oklch(0.968 0.009 214.3)', // #EEF6F8
+      100: 'oklch(0.933 0.018 218.4)', // #DCECF1
+      200: 'oklch(0.869 0.034 217.8)', // #BCDAE3
+      300: 'oklch(0.778 0.056 218.7)', // #8FC0CF
+      400: 'oklch(0.668 0.076 219.7)', // #5BA0B5
+      500: 'oklch(0.558 0.087 221.8)', // #2C7F98
+      600: 'oklch(0.492 0.085 223.3)', // #176B84
+      700: 'oklch(0.443 0.079 224.9)', // #0E5C74 Petrol
+      800: 'oklch(0.389 0.069 224.6)', // #0B4C60
+      900: 'oklch(0.333 0.057 224.7)', // #0A3C4C
+      950: 'oklch(0.267 0.044 225.3)', // #072A36
+    },
+  },
+  darkMode: {
+    gray: {
+      50: 'oklch(0.966 0.005 247.9)', // #F1F4F7
+      100: 'oklch(0.926 0.009 247.9)', // #E2E7EC
+      200: 'oklch(0.848 0.015 251.2)', // #C6CED7
+      300: 'oklch(0.744 0.021 252.9)', // #A3ADB9
+      400: 'oklch(0.589 0.026 256.2)', // #737E8D muted tier, kept under AA
+      450: 'oklch(0.562 0.025 254.5)', // #6B7684
+      500: 'oklch(0.459 0.025 252.7)', // #4E5966
+      600: 'oklch(0.375 0.025 253.1)', // #38424E
+      700: 'oklch(0.317 0.023 253.6)', // #2A333E
+      800: 'oklch(0.266 0.021 257.3)', // #1F2630
+      900: 'oklch(0.233 0.020 258.4)', // #181E27
+      950: 'oklch(0.203 0.016 256.8)', // #12171E sheet
+    },
+    blue: {
+      50: 'oklch(0.953 0.018 214.4)', // #E3F3F7
+      100: 'oklch(0.897 0.038 215.5)', // #C2E4ED
+      200: 'oklch(0.819 0.065 216.2)', // #93CFDF
+      300: 'oklch(0.732 0.087 216.9)', // #62B6CC Petrol, lit
+      400: 'oklch(0.642 0.093 219.1)', // #3F9AB3
+      500: 'oklch(0.557 0.087 220.5)', // #2A7F97
+      600: 'oklch(0.476 0.077 221.3)', // #1D667B
+      700: 'oklch(0.410 0.066 222.2)', // #165264
+      800: 'oklch(0.344 0.054 222.1)', // #113F4D
+      900: 'oklch(0.290 0.044 222.4)', // #0D303B
+      950: 'oklch(0.241 0.034 222.0)', // #0A232B
+    },
+  },
+}
+
+/**
+ * Semantic entries set after the ramps resolve. `canvas` is the Mist frame the
+ * app shell paints behind its sheets; the sidebar shares it so the frame reads
+ * as one continuous surface.
+ */
+export const semantic = {
+  light: {
+    surface: {
+      canvas: 'oklch(0.954 0.005 247.9)', // Mist
+      sidebar: 'oklch(0.954 0.005 247.9)',
+    },
+  },
+  dark: {
+    surface: {
+      canvas: 'oklch(0.171 0.012 254.2)', // #0C1015, below the sheet
+      sidebar: 'oklch(0.171 0.012 254.2)',
+    },
+  },
+}
+
+/** The interface family. Declared by `@talelk/newui-tailwind`'s font CSS. */
+export const fontFamily = { text: 'IBM Plex Sans' }
+
+/**
+ * Type sizes replaced in the exported scale: 13px interface text, quieter
+ * headings that lean on weight rather than size.
+ */
+export const fontSize = {
+  interface: { fontSize: '13px', lineHeight: '18px', letterSpacing: '0em' },
+  caption: { fontSize: '12px', lineHeight: '16px', letterSpacing: '0em' },
+  section: { fontSize: '15px', lineHeight: '20px', letterSpacing: '-0.005em' },
+  heading: { fontSize: '20px', lineHeight: '26px', letterSpacing: '-0.015em' },
+  metric: { fontSize: '22px', lineHeight: '28px', letterSpacing: '-0.02em' },
+  hero: { fontSize: '32px', lineHeight: '38px', letterSpacing: '-0.025em' },
+  base: { fontSize: '13px', lineHeight: '18px', letterSpacing: '0em' },
+  sm: { fontSize: '12px', lineHeight: '16px', letterSpacing: '0em' },
+  xs: { fontSize: '11px', lineHeight: '14px', letterSpacing: '0.005em' },
+  '2xs': { fontSize: '10.5px', lineHeight: '13px', letterSpacing: '0.01em' },
+  md: { fontSize: '14px', lineHeight: '20px', letterSpacing: '0em' },
+  lg: { fontSize: '15px', lineHeight: '20px', letterSpacing: '0em' },
+  'p-base': { fontSize: '13px', lineHeight: '20px', letterSpacing: '0em' },
+  'p-sm': { fontSize: '12px', lineHeight: '18px', letterSpacing: '0em' },
+}
+
+/** Plex needs no positive tracking at text sizes; weights share the size's. */
+export function trackingFor(size) {
+  return fontSize[size]?.letterSpacing
+}
+
+/** Radius by role: 4px controls, 6px sheets and cards, 8px overlays. */
+export const radiusRoles = {
+  control: '4px',
+  card: '6px',
+  overlay: '8px',
+}
+
+/**
+ * Focus rings, as the export's `0 0 0 <spread> <color>` shapes. The export's
+ * default ring is light gray (about 1.6:1 on white); here focus is the accent,
+ * solid, 3:1 or better against both the sheet and the frame.
+ */
+export const focus = {
+  light: {
+    default: '0px 0px 0px 2px #0E5C74',
+    blue: '0px 0px 0px 2px #0E5C74',
+  },
+  dark: {
+    default: '0px 0px 0px 2px #62B6CC',
+    blue: '0px 0px 0px 2px #62B6CC',
+  },
+}

package/src/tokens/layers.js

@@ -4,7 +4,8 @@
  * Components never hard-code a z-index or a transition duration: they name the
  * layer's role or the speed's role, and this scale owns the number. Six stacked
  * layers cover the kit — content, raised chrome, floating chrome, overlays and
- * the topmost hover layer — and three durations cover transition speeds.
+ * the topmost hover layer — and the named durations cover every transition and
+ * animation speed a component may use.
  */
 export const zIndex = {
   raised: 10,
@@ -14,12 +15,21 @@ export const zIndex = {
 }
 
 export const duration = {
+  instant: '75ms',
   fast: '100ms',
   base: '150ms',
+  moderate: '200ms',
   slow: '300ms',
+  progress: '660ms',
 }
 
 export const easing = {
   /** The kit's standard ease-in-out curve (progress fills, drawers). */
   standard: 'cubic-bezier(0.65, 0, 0.35, 1)',
+  /** Enter/disclosure: fast arrival, gentle settle (disclosure-panel, overlays). */
+  out: 'cubic-bezier(0.23, 1, 0.32, 1)',
+  /** Exit: slow departure, fast finish. */
+  in: 'cubic-bezier(0.5, 0, 0.75, 0)',
+  /** The standard curve under Tailwind's conventional name. */
+  'in-out': 'cubic-bezier(0.65, 0, 0.35, 1)',
 }