From aa975577457aad1700f50bc649a12566ca080f75 Mon Sep 17 00:00:00 2001 From: Frida Date: Mon, 20 Jul 2026 15:43:09 +0200 Subject: [PATCH 1/2] docs: mark old token systems as deprecated and transitional --- packages/eds-tokens/CHANGELOG.md | 8 +++++++ packages/eds-tokens/README.md | 30 +++++++++++++++++++++------ packages/eds-tokens/package.json | 2 +- packages/eds-tokens/src/base/index.ts | 7 +++++++ 4 files changed, 40 insertions(+), 7 deletions(-) diff --git a/packages/eds-tokens/CHANGELOG.md b/packages/eds-tokens/CHANGELOG.md index 55c8a58670..007ac828e9 100644 --- a/packages/eds-tokens/CHANGELOG.md +++ b/packages/eds-tokens/CHANGELOG.md @@ -12,6 +12,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 * update tokens from Tokens Studio release ([#5182](https://github.com/equinor/design-system/issues/5182)) ([6074f72](https://github.com/equinor/design-system/commit/6074f721b4072741c50498d63c10ab3ebe45185e)) +## [2.3.2](https://github.com/equinor/design-system/compare/eds-tokens@v2.3.1...eds-tokens@v2.3.2) (2026-07-20) + +Documentation-only release — no token changes. + +### 📝 Documentation + +* mark the legacy `tokens` JavaScript object as deprecated (do not use in new code) and flag the CSS variables as transitional: still the supported option for production, but the variable names will be replaced by the new token structure (currently on `@equinor/eds-tokens@beta`) in the next major release ([#5120](https://github.com/equinor/design-system/issues/5120)) + ## [2.3.1](https://github.com/equinor/design-system/compare/eds-tokens@v2.3.0...eds-tokens@v2.3.1) (2026-06-23) diff --git a/packages/eds-tokens/README.md b/packages/eds-tokens/README.md index 02f69b64f8..1e0bc943cb 100644 --- a/packages/eds-tokens/README.md +++ b/packages/eds-tokens/README.md @@ -13,14 +13,32 @@ pnpm add @equinor/eds-tokens ## Usage +> **⚠️ Transition notice.** The token structure in this package is being +> replaced. The replacement is developed on the beta line +> (`@equinor/eds-tokens@beta`) and ships as the next major release. +> +> * **Need tokens today?** Use the CSS variables — they are the supported +> option for production and keep working throughout 2.x. Expect the +> variable names to change in the next major release; keeping direct +> variable references few and centralised will make that migration cheap. +> * **Do not** adopt the legacy `tokens` JavaScript object in new code — it +> is deprecated and will be removed in the next major release. +> * The beta line is for testing and feedback, not production use. + The package provides two token systems: -* **CSS Variables (Recommended)** -- Modern, theme-aware design tokens synced from Figma -* **Legacy Tokens** -- Original token format, still supported for backward compatibility +* **CSS Variables** -- Theme-aware design tokens synced from Figma. Supported for production; the variable names will change in the next major release. +* **Legacy Tokens** -- Original token format. Deprecated: do not use in new code. --- -## CSS Variables (Recommended) +## CSS Variables + +> These `--eds-*` variables will be replaced by the new token structure in +> the next major release. They remain the supported way to consume EDS +> tokens today (`@equinor/eds-core-react` 2.x requires `css/variables`) — +> just keep direct variable references organised so the rename in the next +> major is easy to absorb. The new token system uses CSS custom properties that automatically adapt to light and dark color schemes via explicit `[data-color-scheme]` scope rules with a `prefers-color-scheme` media-query fallback. These tokens are directly synced from Figma variables. @@ -309,9 +327,9 @@ These utilities use modern CSS features (`text-box-trim`) and gracefully degrade --- -## Legacy Tokens (Backward Compatible) +## Legacy Tokens (deprecated — do not use) -The original token format is still available for existing applications. These tokens use a structured JavaScript object format. +**Deprecated.** The original token format remains published only so existing applications keep working, and will be removed in the next major release. These tokens use a structured JavaScript object format. ### Using Legacy Tokens in JavaScript/TypeScript @@ -334,7 +352,7 @@ const typography = tokens.typography.heading.h1 * Interaction states * Typography (`ot`, `woff` or `woff2` font required) -> We recommend migrating to CSS Variables for new projects to benefit from automatic theme support and better performance. +> Do not adopt these legacy tokens in new projects. If you need tokens today, use the CSS variables above; the long-term replacement is the new token structure currently on the beta line (`@equinor/eds-tokens@beta`). [design tokens]: https://css-tricks.com/what-are-design-tokens/ diff --git a/packages/eds-tokens/package.json b/packages/eds-tokens/package.json index 37f063c5a5..cc063deae2 100644 --- a/packages/eds-tokens/package.json +++ b/packages/eds-tokens/package.json @@ -1,6 +1,6 @@ { "name": "@equinor/eds-tokens", - "version": "2.3.1", + "version": "2.3.2", "description": "Design tokens for the Equinor Design System", "type": "module", "exports": { diff --git a/packages/eds-tokens/src/base/index.ts b/packages/eds-tokens/src/base/index.ts index 53cea3784b..217e3cc16d 100644 --- a/packages/eds-tokens/src/base/index.ts +++ b/packages/eds-tokens/src/base/index.ts @@ -6,6 +6,13 @@ import { shape } from './shape' import { typography } from './typography' import { spacings } from './spacings' +/** + * @deprecated Do not use in new code — this legacy token object will be + * removed in the next major release. If you need tokens today, use the CSS + * variables (`@equinor/eds-tokens/css/variables`); the long-term + * replacement is the new token structure on the beta line + * (`@equinor/eds-tokens@beta`). + */ export const tokens = { clickbounds, colors, From e87a25f83b0e4e0f54d56b474a5d6b866b6d7db4 Mon Sep 17 00:00:00 2001 From: Frida Date: Mon, 20 Jul 2026 15:58:30 +0200 Subject: [PATCH 2/2] docs: replace legacy tokens example with CSS variables in getting started guide --- .../develop/getting_started_development.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/apps/design-system-docs/docs/about/getting-started/develop/getting_started_development.md b/apps/design-system-docs/docs/about/getting-started/develop/getting_started_development.md index c77e10be34..58524f0e20 100644 --- a/apps/design-system-docs/docs/about/getting-started/develop/getting_started_development.md +++ b/apps/design-system-docs/docs/about/getting-started/develop/getting_started_development.md @@ -54,17 +54,21 @@ For consistent styling, install and use design tokens: npm install @equinor/eds-tokens ``` -```javascript -import { tokens } from '@equinor/eds-tokens' +Import the CSS variables and use them in your styles: -const { typography, colors } = tokens +```css +@import '@equinor/eds-tokens/css/variables'; -const styles = { - fontSize: typography.heading.h1.fontSize, - color: colors.interactive.primary__resting.rgba, +.my-component { + background-color: var(--eds-color-bg-neutral-surface); + color: var(--eds-color-text-neutral-strong); } ``` +:::note +The token structure is being replaced. The CSS variables are the supported option today, but the variable names will change in the next major release of `@equinor/eds-tokens`, so keep direct variable references few and centralised. The older `tokens` JavaScript object is deprecated and should not be used in new code. See the [package README](https://www.npmjs.com/package/@equinor/eds-tokens) for details. +::: + ## Key Features **TypeScript support:** Full autocomplete, type checking, and inline documentation included.