@knime/kds-styles 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @knime/kds-styles
 
+## 2.4.0
+
+### Minor Changes
+
+- b4222fa: Design tokens are now exported as structured TypeScript constants mirroring the
+  token JSON structure (KDS-690). `@knime/kds-styles/tokens` exposes one constant
+  per top-level token group (`color`, `dimension`, `spacing`, `border`,
+  `borderRadius`, `borderWidth`, `elevation`, `boxShadow`, `fakeBorder`, `font`,
+  `sizing`, `width`) plus the value types (`KdsColor`, `KdsDimension`,
+  `KdsTypography`, ...). Color values are always `{ light, dark }` pairs of HSL
+  component objects (`{ h, s, l, alpha }`); dimensional values are
+  `{ value, unit }` objects; composite tokens (border, elevation, typography)
+  stay structured objects. Every token additionally carries its CSS
+  representation in `css`: the exact value from the emitted CSS custom
+  properties (`css.value`, e.g. `light-dark(...)` for colors or the complete
+  font shorthand for typography) and the custom property reference
+  (`css.variable`, e.g. `var(--kds-color-surface-default)`). The exports are
+  shipped precompiled (ESM `.js` + `.d.ts`), so they also work in plain Node.js
+  without any TypeScript setup.
+
+  The previous flat camelCase px constants (e.g.
+  `kdsDimensionComponentHeight1p5x`) and the `kdsCore*` primitives were removed
+  from `@knime/kds-styles/tokens`; they were only used internally in this
+  repository and all usages have been migrated to the structured exports.
+
+  The CSS variables now carry the exact hsl values authored in the token sources:
+  the previously applied color transform rounded h/s/l components (e.g. `15.7%`
+  became `16%`) and rewrote the hue of zero-saturation grays. CSS and TS color
+  values are now numerically identical.
+
+## 2.3.0
+
 ## 2.2.0
 
 ### Patch Changes

package/README.md

@@ -24,6 +24,8 @@ All token values are fully calculated, ensuring that no variable references rema
 
 Two sets of files are generated for light and dark mode. Subsequently, the CSS files are merged to contain all variables only once. For variables that use different color values in light and dark mode, the `light-dark()` function is employed.
 
+In the TypeScript exports, color values are always emitted as `{ light, dark }` pairs (colors are the only mode-dependent token values); all other values are identical in both modes and stay plain.
+
 ## Fonts
 
 The design system uses the Roboto, Roboto Condensed and Roboto Mono fonts for typography. When using `@knime/kds-styles` as a dependency the fonts will automatically be installed, no separate dependency is needed.
@@ -39,6 +41,25 @@ To use the design tokens and basic CSS you can simply import the following into
 
 - `@import "@knime/kds-styles/index.css"`: Bundles all previous imports and adds basic core style rules, e.g. uses modern-normalize for browser reset. **Important:** Use only for new projects, or if conversion is already at a point where core styles can be replaced.
 
+### Design Tokens in JavaScript/TypeScript
+
+For cases where CSS variables cannot be used (e.g. layout calculations, canvas rendering or JavaScript services), the design tokens are also exported as TypeScript constants. They are shipped precompiled (ESM `.js` + `.d.ts`), so they work in any environment — including plain Node.js — without additional setup:
+
+```ts
+import { color, dimension, font } from "@knime/kds-styles/tokens";
+
+dimension.component.height["1.5x"].value; // 24 (px)
+dimension.component.height["1.5x"].css.value; // "24px"
+color.surface.default.light; // { h: 0, s: 0, l: 98, alpha: 1 }
+color.surface.default.dark; // { h: 0, s: 0, l: 15.7, alpha: 1 }
+color.surface.default.css.value; // "light-dark(hsl(0, 0%, 98%), hsl(0, 0%, 15.7%))"
+color.surface.default.css.variable; // "var(--kds-color-surface-default)"
+font.base.display.small.fontSize; // { value: 20, unit: "px" }
+font.base.display.small.css.value; // "700 20px/normal Roboto, sans-serif"
+```
+
+The exports mirror the token JSON structure (without the `kds` root): one constant per top-level token group plus the value types (`KdsColor`, `KdsDimension`, `KdsTypography`, ...). Dimensional values are `{ value, unit }` objects, color values are always `{ light, dark }` pairs of HSL component objects (equivalent to the CSS color `hsl(<h> <s>% <l>% / <alpha>)`), and composite tokens (border, elevation, typography) remain structured objects. Every token additionally carries its CSS representation in `css`: the exact value from the emitted CSS custom properties (`css.value`, including `light-dark()` for colors and complete shorthands for composite tokens) and the custom property reference (`css.variable`). The internal `core` primitives are intentionally not emitted — their values are already inlined into the semantic tokens, which are the only ones consumers should use.
+
 ## Important Scripts
 
 Here are some of the most important scripts defined in the [`package.json`](package.json):