docs: mark old token systems as deprecated and transitional (#5191)

* docs: mark old token systems as deprecated and transitional

* docs: replace legacy tokens example with CSS variables in getting started guide

Author: pomfrida

apps/design-system-docs/docs/about/getting-started/develop/getting_started_development.md

@@ -58,17 +58,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.

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)
 
 

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/
 

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": {

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,