@equinor/eds-tokens 1.1.2 → 1.1.3

package/README.md

@@ -2,6 +2,9 @@
 
 [Design tokens] used in the <abbr title="Equinor Design System">EDS</abbr>, including colors, spacing, typography, and more. These tokens are synchronized with Figma variables and provide a single source of truth for design decisions across the design system.
 
+
+> For <abbr title="Large Language Model">LLM</abbr> instructions on using colors, see the [instructions/colors.md](./instructions/colors.md), or jump directly to the [static](./instructions/colors-static.md) or [dynamic](./instructions/colors-dynamic.md) instructions.
+
 ## Installation
 
 ```sh
@@ -91,6 +94,41 @@ const padding = comfortableSpacing.SPACING_INLINE_MD
 const borderRadius = comfortableSpacing.SPACING_BORDER_RADIUS_ROUNDED
 ```
 
+### Importing variables as JSON
+
+The variables are available in two formats:
+
+* **Flat format** (`/flat/`) -- Simple key-value pairs for easy access
+* **Nested format** (`/nested/`) -- Hierarchical structure matching the token naming
+
+* The semantic color tokens are available for light and dark color schemes.
+
+* `light-semantic.json` / `dark-semantic.json` -- Semantic color tokens for each color scheme
+
+#### Flat Format
+
+```typescript
+// Import flat format tokens
+import lightSemanticFlat from '@equinor/eds-tokens/json/color/color-scheme/flat/light-semantic.json'
+import darkSemanticFlat from '@equinor/eds-tokens/json/color/color-scheme/flat/dark-semantic.json'
+
+// Access values directly
+const lightSurface = lightSemanticFlat['bg-neutral-surface'] // "#ffffff"
+const darkSurface = darkSemanticFlat['bg-neutral-surface'] // "#262626"
+```
+
+#### Nested Format
+
+```typescript
+// Import nested format tokens
+import lightSemanticNested from '@equinor/eds-tokens/json/color/color-scheme/nested/light-semantic.json'
+import darkSemanticNested from '@equinor/eds-tokens/json/color/color-scheme/nested/dark-semantic.json'
+
+// Access values via hierarchical structure
+const lightSurface = lightSemanticNested.bg.neutral.surface // "#ffffff"
+const darkSurface = darkSemanticNested.bg.neutral.surface // "#262626"
+```
+
 ### Available Token Categories
 
 * **Colors** -- Semantic color tokens for backgrounds, text, borders, and states

package/instructions/colors-dynamic.md

@@ -0,0 +1,114 @@
+---
+applyTo: '**'
+---
+
+# Dynamic Color Approach
+
+The dynamic approach uses abstraction with variable modes in Figma and data attributes in code to define the semantic category at runtime. The same component can work with different semantic meanings without changing code.
+
+:::tip
+
+See [colors.md](./colors.md) for core color system concepts.
+
+:::
+
+## Concept
+
+Variables use abstract role names (background, text, border) without specifying the semantic category. The semantic category is applied using the `data-color-appearance` attribute.
+
+## Naming Pattern
+
+Dynamic variable names follow this pattern:
+
+```
+--eds-color-[role]-[priority]-[state]
+```
+
+**Examples:**
+
+- `--eds-color-bg-fill-emphasis-default`
+- `--eds-color-text-strong-on-emphasis`
+- `--eds-color-border-subtle`
+
+Note: No semantic category (accent, neutral, etc.) in the variable name itself.
+
+## CSS Variables
+
+### Import
+
+```css
+@import '@equinor/eds-tokens/css/variables';
+```
+
+### Setting Appearance
+
+Use the `data-color-appearance` attribute to set the semantic category:
+
+```html
+<!-- Accent appearance -->
+<button data-color-appearance="accent">Primary</button>
+
+<!-- Neutral appearance (default) -->
+<button data-color-appearance="neutral">Secondary</button>
+
+<!-- Success appearance -->
+<button data-color-appearance="success">Confirm</button>
+
+<!-- Warning appearance -->
+<button data-color-appearance="warning">Caution</button>
+
+<!-- Danger appearance -->
+<button data-color-appearance="danger">Delete</button>
+
+<!-- Info appearance -->
+<button data-color-appearance="info">Info</button>
+```
+
+### Usage
+
+Use abstract role variables in your CSS:
+
+```css
+.button {
+  background-color: var(--eds-color-bg-fill-emphasis-default);
+  color: var(--eds-color-text-strong-on-emphasis);
+  border: 1px solid var(--eds-color-border-strong);
+}
+
+.button:hover {
+  background-color: var(--eds-color-bg-fill-emphasis-hover);
+}
+
+.button:active {
+  background-color: var(--eds-color-bg-fill-emphasis-active);
+}
+```
+
+Now the same component works with any appearance:
+
+```html
+<!-- All use the same CSS class but different appearances -->
+<button class="button" data-color-appearance="accent">Primary</button>
+<button class="button" data-color-appearance="neutral">Secondary</button>
+<button class="button" data-color-appearance="success">Success</button>
+```
+
+## Appearance Values
+
+Use one of these values for the `data-color-appearance` attribute:
+
+- `neutral` (default) -- Base and supporting colors
+- `accent` -- Brand and highlight colors
+- `success` -- Positive or confirming feedback
+- `info` -- Communication and neutral messages
+- `warning` -- Cautionary states
+- `danger` -- Destructive or error states
+
+## Best Practices
+
+- **Use abstraction** -- Write CSS once, reuse with different appearances
+- **Set appearance semantically** -- Use the attribute based on context, not styling needs
+- **Keep appearance stable** -- Don't change appearances based on hover/active states
+- **Test all appearances** -- Verify your component works with all appearance values
+- **Document requirements** -- Make clear which appearances work with your component
+- **Never mix approaches** -- Use dynamic consistently, don't mix with static

package/instructions/colors-static.md

@@ -0,0 +1,80 @@
+---
+applyTo: '**'
+---
+
+# Static Color Approach
+
+The static approach uses a complete set of variables for each semantic category. Each variable explicitly specifies the semantic category in its name.
+
+> See [colors.md](./colors.md) for the core color system concepts.
+
+## Concept
+
+In the static approach, each semantic category (accent, neutral, info, success, warning, danger) has its own variables. You choose the specific variable you need based on the semantic meaning required.
+
+## Naming Pattern
+
+Static variable names follow this pattern:
+
+```
+--eds-color-[role]-[semantic category]-[priority]-[state]
+```
+
+> **Note:** The `[state]` suffix (e.g., `-default`, `-hover`, `-active`) is only present for certain roles, such as background fill. For text and border variables, the state is typically omitted.
+
+- `--eds-color-bg-accent-fill-emphasis-default` -- Accent semantic category (background fill, with default state)
+- `--eds-color-bg-neutral-fill-muted-default` -- Neutral semantic category (background fill, with default state)
+- `--eds-color-border-danger-medium` -- Danger semantic category (border, no state)
+- `--eds-color-text-success-strong` -- Success semantic category (text, no state)
+
+## CSS Variables
+
+### Import
+
+```css
+@import '@equinor/eds-tokens/css/variables';
+```
+
+### Usage
+
+Use specific semantic variables in your styles:
+
+```css
+.button-primary {
+  background-color: var(--eds-color-bg-accent-fill-emphasis-default);
+  color: var(--eds-color-text-accent-strong-on-emphasis);
+  border: 1px solid var(--eds-color-border-accent-strong);
+}
+
+.alert-warning {
+  background-color: var(--eds-color-bg-warning-fill-emphasis);
+  color: var(--eds-color-text-warning-strong-on-emphasis);
+  border-left: 4px solid var(--eds-color-border-warning-strong);
+}
+```
+
+### Interactive States
+
+Background fill-muted and fill-emphasis include state variants for hover and active:
+
+```css
+.button {
+  background-color: var(--eds-color-bg-accent-fill-emphasis-default);
+  transition: background-color 0.2s;
+}
+
+.button:hover {
+  background-color: var(--eds-color-bg-accent-fill-emphasis-hover);
+}
+
+.button:active {
+  background-color: var(--eds-color-bg-accent-fill-emphasis-active);
+}
+```
+
+## Best Practices
+
+- **Be explicit** -- Choose the specific semantic category your element needs
+- **Pair carefully** -- Always use matching text and background variables for contrast
+- **Never mix approaches** -- Use static consistently, don't mix with dynamic
+- **Test contrast** -- Verify all color combinations meet accessibility standards

package/instructions/colors.md

@@ -0,0 +1,123 @@
+---
+applyTo: '**'
+---
+
+# Color System Introduction
+
+This guide introduces the <abbr title="Equinor Design System">EDS</abbr> color system -- semantic meaning, token categories, and how to choose the right approach for your project.
+
+## Core Concepts
+
+The <abbr title="Equinor Design System">EDS</abbr> color system is built on **semantic meaning**, not visual appearance. You choose colors based on **function and role** in the interface, not on how they look.
+
+### Semantic Categories
+
+All colors belong to one of six semantic categories that reflect their purpose:
+
+- **Accent** -- Brand and highlight colors
+- **Neutral** -- Base and supporting colors
+- **Info** -- Communication and neutral messages
+- **Success** -- Positive or confirming feedback
+- **Warning** -- Cautionary states
+- **Danger** -- Destructive or error states
+
+### Color Roles
+
+Within each semantic category, colors serve specific roles:
+
+- **Background (`bg`)** -- Surface and canvas layers
+  - `surface` -- Placed on canvas to create depth in layouts
+  - `canvas` -- Main application background
+  - `fill-muted` -- Subtle backgrounds for interactive elements
+  - `fill-emphasis` -- Bold backgrounds for prominent interactive elements
+
+- **Border** -- Separators and outlines
+  - `subtle` -- Light separators and dividers
+  - `medium` -- Standard borders and controls
+  - `strong` -- Emphasis or interactive elements
+
+- **Text** -- Content and readability
+  - `strong` -- Primary text in the application
+  - `subtle` -- Secondary text and less important content
+  - `strong-on-emphasis` -- Text on emphasis backgrounds
+  - `subtle-on-emphasis` -- Secondary text on emphasis backgrounds
+
+### Concept Colors
+
+Global colors that sit outside the semantic scales for special cases:
+
+- `bg-floating` -- Floating elements like tooltips and menus
+- `bg-backdrop` -- Overlay layer behind modals
+- `bg-input` -- Input fields and forms
+- `border-focus` -- Focus rings for accessibility
+- `text-link` -- Default link color
+
+## Two Approaches: Static vs. Dynamic
+
+The <abbr title="Equinor Design System">EDS</abbr> color system offers two approaches. Both use the same color values and accessibility logic but differ in how you apply and manage them.
+
+:::warning
+
+**Choose one approach and use it consistently** across design and development. Mixing approaches causes design and code to drift apart, making development harder. Each Figma variable has a matching code variable -- keep them aligned.
+
+:::
+
+### Static Approach
+
+Each semantic category has its own complete set of variables.
+
+- **When to use:** Fixed semantic meanings throughout your interface
+- **Example:** All primary buttons always use `accent` colors
+- **More info:** See [colors-static.md](./colors-static.md)
+
+### Dynamic Approach
+
+Uses abstraction with variable modes in Figma and data attributes in code to define semantic category at runtime.
+
+- **When to use:** Need to change semantic meaning without updating components
+- **Example:** Same button component can switch from `accent` to `neutral` context
+- **More info:** See [colors-dynamic.md](./colors-dynamic.md)
+
+## Accessibility
+
+All color combinations have been evaluated using the **<abbr title="Accessible Perceptual Contrast Algorithm">APCA</abbr>** contrast algorithm:
+
+**Key principle:** Always pair text colors with their intended background tokens. They have been carefully tested together.
+
+## Color Schemes
+
+The color system automatically adapts to light and dark color schemes using the `data-color-scheme` attribute:
+
+```html
+<!-- Light theme (default) -->
+<html data-color-scheme="light"></html>
+
+<!-- Dark theme -->
+<html data-color-scheme="dark"></html>
+```
+
+Or with custom selectors:
+
+```css
+.light {
+  color-scheme: light;
+}
+.dark {
+  color-scheme: dark;
+}
+```
+
+Both the static and dynamic libraries support light and dark modes automatically.
+
+## Installation
+
+```bash
+pnpm add @equinor/eds-tokens
+```
+
+## Next Steps
+
+Choose your approach and refer to the specific guide:
+
+- **Static Approach:** See [colors-static.md](./colors-static.md)
+- **Dynamic Approach:** See [colors-dynamic.md](./colors-dynamic.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/eds-tokens",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Design tokens for the Equinor Design System",
   "type": "module",
   "exports": {
@@ -41,6 +41,7 @@
     "dist/*",
     "build/*",
     "commonjs/*",
+    "instructions/*",
     "tokens.css",
     "elements.css"
   ],