@knime/kds-styles 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @knime/kds-styles
 
+## 5.0.0
+
+### Major Changes
+
+- 0cc879e: BREAKING CHANGES:
+
+  - `index.css`:
+    - declare `color-scheme: light dark` on `:root`, so apps importing it follow the device light/dark preference instead of always rendering light. Every `--kds-*` color token resolves through `light-dark()`, so on a dark-mode device the UI — plus browser chrome such as scrollbars, form controls and the default canvas background — switches to dark with no opt-in on the consumer's side.
+    - partially migrated apps are most affected: legacy `--knime-*` properties are hard-coded light and ignore `light-dark()`, so those parts stay light next to the now-dark tokenized parts.
+    - to keep the previous always-light rendering, declare `:root { color-scheme: light; }` in the app. Apps importing only `kds-variables.css` are unaffected — see "Enabling Dark Mode" in the package README.
+
 ## 4.0.0
 
 ## 3.0.0

package/README.md

@@ -40,6 +40,24 @@ 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.
 
+### Enabling Dark Mode
+
+The color tokens resolve through `light-dark()`, so the root element's `color-scheme` decides light vs. dark. Its default (`normal`) resolves every token to its light value — an app that never sets it renders light on a dark device.
+
+`index.css` declares `color-scheme: light dark` on `:root`, which makes it **the recommended import for apps that are completely dark-mode-ready**: no JavaScript, and it applies on the first (even server-rendered) paint, so nothing flickers on hydration.
+
+An app that cannot import `index.css` yet — e.g. it still needs the `@knime/styles` reset and only imports `kds-variables.css` — can declare the property itself:
+
+```css
+:root {
+  color-scheme: light dark;
+}
+```
+
+Do so deliberately if the app is only partially migrated: legacy `--knime-*` properties are hard-coded light and ignore `light-dark()`, so those parts stay light, and `color-scheme` also switches browser chrome (scrollbars, form controls, canvas background).
+
+For an explicit user override, call `useKdsDarkMode()` from `@knime/kds-components`. It writes `color-scheme` inline on `<html>`, winning over the rule above. It needs a DOM, so in a server-rendered app call it from client-only code and leave the `system` default to CSS.
+
 ### 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:

package/dist/css/basics.css

@@ -1,5 +1,13 @@
 :root {
   font-family: var(--kds-core-font-family-roboto), sans-serif;
+
+  /*
+   * Follow the device preference. The color tokens resolve via `light-dark()`,
+   * so this needs no JavaScript and applies on the first paint.
+   * `useKdsDarkMode()` overrides it with an inline style for an explicit
+   * light/dark preference.
+   */
+  color-scheme: light dark;
 }
 
 body {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knime/kds-styles",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Package containing the design tokens and icons for the KNIME Design System",
   "repository": {
     "type": "git",