@aziontech/theme 1.13.0 → 2.0.0

package/src/tokens/README.md

@@ -1,345 +1,379 @@
+<h1 align="center">azion-theme · tokens</h1>
 
-<h1 align="center">azion-theme</h1>
+Design tokens organized as JavaScript modules, compiled into CSS custom properties and a Tailwind config. The pipeline emits **two parallel targets** from the same source:
 
-![production](https://github.com/aziontech/azion-theme/actions/workflows/release.yml/badge.svg)
+- **`dist/v3/`** — Tailwind v3 preset (`tailwind-preset.js` / `tailwind.config.js`) + a self-contained `globals.css` with `@tailwind` directives, `:root` / `[data-theme=dark]` blocks, responsive `@media` overrides, and the component classes.
+- **`dist/v4/`** — Tailwind v4 CSS-first output: `globals.css` with `@import "tailwindcss"` + `@theme { … }` + plain `:root` for shape/typography semantics + `@layer components`.
 
-<p align="center">
-    <img
-        src="./doc/cover-image.png"
-        width="1200px"
-    />
-</p>
+Tokens live in JS as the source-of-truth and are compiled at package build time, not in the browser.
 
-The Azion Theme repository is focused on sharing our style kit across interfaces and should be used in all company projects, including Azion Console Kit, Azion Site, Landing Pages, and all user interactions with Azion.
+## 📋 Table of contents
 
-## 📋 Table of Contents
+- [Architecture overview](#-architecture-overview)
+- [File structure](#-file-structure)
+- [Token types](#-token-types)
+- [Building & consuming](#-building--consuming)
+- [How to add a new token](#-how-to-add-a-new-token)
+- [Token references (`tokenRef`)](#-token-references-tokenref)
+- [Test pages](#-test-pages)
+- [Theme switching](#-theme-switching)
 
-- [Installation](#-installation)
-- [Usage](#-usage)
-- [Development](#-development)
-- [Design Tokens](#-design-tokens)
-- [Links](#-links)
+---
 
-## 🚀 Installation
+## 🏗 Architecture overview
 
-To install the `azion-theme` project, you need to follow the command. Choose one of your preferences: npm or yarn:
+Three layers:
 
-```bash
-npm install azion-theme --save
-# or
-yarn add azion-theme
-```
+1. **Primitives** — raw, theme-invariant values (color hexes, px sizes, font sizes, durations).
+2. **Semantic / theme** — light/dark variants and responsive (per-breakpoint) tokens that **reference** primitives via `tokenRef(...)`.
+3. **Output bundles** — `dist/v3/` and `dist/v4/` artifacts emitted by `scripts/build-tokens.mjs`.
 
-Alternatively, you can configure the `package.json` file by adding the dependency:
+Compile pipeline:
 
-```json
-{
-  "dependencies": {
-    "azion-theme": "^1.4.0"
-  }
-}
+```
+tokens/primitives/**          ─┐
+                               │
+tokens/semantic/colors.js     ─┤
+tokens/semantic/*.data.js     ─┼──►  scripts/build-tokens.mjs  ──►  dist/v3/{globals.css,tailwind-preset.js,tailwind.config.js}
+tokens/theme/**               ─┤                                    dist/v4/globals.css
+                               │
+scripts/{compile-primitives,  ─┘
+        compile-theme,
+        resolve,
+        css-vars,
+        refs}.js  (building blocks used by build-tokens.mjs)
 ```
 
-After updating the `package.json` file, run `npm install` in the root of your project to install the Azion Theme.
+- Primitives emit a single block (values don't change between themes).
+- Semantic colors flip between `:root, [data-theme=light]` and `[data-theme=dark], .dark, .azion.azion-dark`.
+- Responsive semantic tokens (containers, spacings, texts) emit `@media (min-width: …)` overrides.
 
-### 🔗 Integration with Front-End Project
+---
 
-To integrate the Azion Theme into your front-end project, you need to import the theme files in your project's entry point file (App.vue, main.js, index.js, etc.):
+## 📂 File structure
 
-```javascript
-import 'azion-theme/dark';
-import 'azion-theme/light';
+```
+src/
+├── tokens/
+│   ├── primitives/
+│   │   ├── colors/
+│   │   │   ├── colors.js        # base, blue, gray, violet, orange, slate, yellow,
+│   │   │   │                    # green, red + surface palettes + brand re-export
+│   │   │   ├── brand.js         # primary, accent, surfaces, absolute
+│   │   │   └── alpha.js         # alpha variants for each palette
+│   │   ├── shape/
+│   │   │   ├── aspect-video.js
+│   │   │   ├── container.js     # container-3xs … container-7xl
+│   │   │   ├── height.js        # h-2 … h-96
+│   │   │   ├── radius.js        # none, sm, DEFAULT, md, lg, xl, 2xl, 3xl, full
+│   │   │   ├── shape.js         # shape aliases (`max-w-*`, etc.)
+│   │   │   ├── size.js          # size-2 … size-96
+│   │   │   ├── spacing.js       # spacing-1 … spacing-96
+│   │   │   └── width.js         # w-3xs … w-7xl (alias → container.X)
+│   │   ├── typography/
+│   │   │   ├── font-family.js   # sans, mono, code
+│   │   │   ├── font-size.js     # text-xs … text-9xl
+│   │   │   ├── font-weight.js   # 100 … 900
+│   │   │   ├── leading.js       # leading-3 … leading-10
+│   │   │   ├── line-height.js   # line-height-none … line-height-loose
+│   │   │   └── tracking.js      # tracking-tighter … tracking-widest
+│   │   ├── effects/
+│   │   │   ├── blur.js          # blur-xs … blur-3xl
+│   │   │   ├── drop-shadow.js
+│   │   │   ├── inset-shadow.js
+│   │   │   ├── opacity.js       # opacity-0 … opacity-100
+│   │   │   ├── perspective.js
+│   │   │   └── shadow.js        # box-shadow scale
+│   │   ├── animations/
+│   │   │   ├── animate.js       # named keyframe animations
+│   │   │   └── ease.js          # easing curves
+│   │   ├── border-widths.js     # border-0 … border-4
+│   │   ├── breakpoints.js       # sm, md, lg, xl, 2xl
+│   │   └── ring-offset.js
+│   ├── theme/
+│   │   ├── primary.js           # primary, primary-mask/hover/contrast
+│   │   ├── secondary.js
+│   │   ├── accent.js
+│   │   ├── surfaces.js          # surface-0 … surface-950 (alias for gray)
+│   │   ├── background.js        # bg-canvas, bg-surface, bg-mask, …
+│   │   ├── border.js            # border-default/muted/strong/selected
+│   │   ├── text.js              # text-default, text-muted
+│   │   ├── ring.js              # ring-color
+│   │   └── feedback/
+│   │       ├── success.js
+│   │       ├── warning.js
+│   │       ├── danger.js
+│   │       └── info.js
+│   ├── semantic/
+│   │   ├── colors.js            # text/background/border semantic refs (consumed by v3 preset)
+│   │   ├── containers.js        # static + responsive container tokens
+│   │   ├── containers.data.js   # `{ key: { sm, md, lg, … } }` data table
+│   │   ├── spacings.js
+│   │   ├── spacings.data.js
+│   │   ├── texts.js
+│   │   ├── texts.data.js        # font-size + line-height + letter-spacing bundles
+│   │   └── animations.js
+│   ├── theme.js                 # Tailwind theme.extend (colors + semantic mappings)
+│   └── index.js                 # public re-exports
+├── scripts/
+│   ├── refs.js                  # tokenRef helper + isTokenRef guard
+│   ├── resolve.js               # resolves `tokenRef` paths to literal values
+│   ├── css-vars.js              # builds light/dark CSS var maps from semantic refs
+│   ├── compile-primitives.js    # flattens primitive trees into CSS vars
+│   ├── compile-theme.js         # legacy theme compiler (used by the harness pages)
+│   └── build-tokens.mjs         # main entrypoint: emits dist/v3 and dist/v4 bundles
+└── tests/
+    ├── primitives.html          # visual harness for all primitives
+    ├── theme.html               # semantic tokens with light/dark toggle
+    └── tokens.html              # combined view
 ```
 
-Make sure to include these imports at the top of your entry point file to ensure the styles are applied correctly throughout your application.
-
-## 💻 Development
+---
 
-To work locally, you should clone both the `azion-theme` repository and the other repository where the theme will be used.
+## 🎨 Token types
 
-### Example:
+### Primitives
 
-In this example, we will use the [azion-webkit](https://github.com/aziontech/azion-webkit) repository:
+Plain JS objects with literal values. Theme-invariant.
 
-1. Clone the `azion-webkit` and `azion-theme` repositories:
-  
-  ```bash
-  git clone https://github.com/aziontech/azion-webkit.git
-  git clone https://github.com/aziontech/azion-theme.git
-  ```
+```js
+// tokens/primitives/colors/brand.js
+export const brandPrimitives = {
+  primary: { 50: '#FFF5EF', 100: '#FFE7D8', /* … */ 500: '#FE601F', /* … */ 950: '#401602' },
+  accent:  { 50: '#F6F6FF', /* … */ 500: '#8A84EC', /* … */ 950: '#0B0A19' },
+  absolute: { black: '#0A0A0A', white: '#FCFCFC' },
+};
+```
 
-2. Install dependencies and create the link point:
-  
-  ```bash
-  cd ./azion-theme && npm i && npm link
-  ```
+```js
+// tokens/primitives/shape/spacing.js
+export const spacing = { 1: '4px', 2: '8px', /* … */ 96: '384px' };
+```
 
-3. Link the `azion-theme` to the `azion-webkit` project:
-  
-  ```bash
-  cd ../azion-webkit && npm i && npm link azion-theme
-  ```
+### Semantic / theme
 
-Any modifications made to `azion-theme` will be reflected on this development server with hot reload.
+Objects with `light` / `dark` variants. Values are `tokenRef(...)` calls that point to primitives.
 
-## 🎨 Design Tokens
+```js
+// tokens/theme/primary.js
+import { tokenRef } from '../../scripts/refs.js';
 
-This project includes **primitive color tokens** extracted directly from Figma, ready to be consumed via Tailwind CSS.
+export const primary = {
+  light: {
+    primary:           tokenRef('brand.primary.primary-500'),
+    'primary-mask':    tokenRef('primitives.alpha.orange.100'),
+    'primary-hover':   tokenRef('brand.primary.primary-600'),
+    'primary-contrast': tokenRef('primitives.base.black'),
+  },
+  dark: {
+    primary:           tokenRef('brand.primary.primary-500'),
+    'primary-mask':    tokenRef('primitives.alpha.orange.100'),
+    'primary-hover':   tokenRef('brand.primary.primary-600'),
+    'primary-contrast': tokenRef('primitives.base.white'),
+  },
+};
+```
 
-### 🚀 How to Use the Tokens
+### Responsive semantic data (`*.data.js`)
 
-```javascript
-// tailwind.config.js
-import typography from '@tailwindcss/typography';
-import { tokenUtilities } from 'azion-theme/tokens/build/tailwind-plugin';
-import colors from 'azion-theme/tokens';
+Containers, spacings, and texts use a per-breakpoint table that `build-tokens.mjs` flattens into `@media` overrides plus matching component classes (`.gap-…`, `.p-…`, `.text-…`, `.px-container`, `.py-container`, `.max-container-width`).
 
-export default {
-  content: ['./src/**/*.{js,ts,jsx,tsx,html}'],
-  darkMode: ['class', '.dark', '.azion.azion-dark'],
-  theme: {
-    extend: {
-      colors: {
-        ...colors,
-      },
-    },
-  },
-  plugins: [tokenUtilities(), typography],
+```js
+// tokens/semantic/spacings.data.js
+export const spacingsData = {
+  'gap-sm': { _: '8px', md: '12px', xl: '16px' },
+  'gap-md': { _: '12px', md: '16px', xl: '24px' },
+  // …
 };
 ```
 
-#### Token structure overview
+`_` is the base value emitted in `:root`; the breakpoint keys (`sm`, `md`, `lg`, `xl`, `2xl`) become media-query overrides.
 
-**Global/Primitive tokens** (direct values, use with `dark:` variant):
-```javascript
-// Primitive palettes (all with 50-950 shades)
-colors.orange[500];           // #fe601f
-colors.violet[500];           // #8a84ec
-colors.neutral[900];          // #171717
+---
 
-// Brand colors
-colors.brand.black;           // #0a0a0a
-colors.brand.white;           // #fafafa
-colors.brand.orange;          // #fe601f
+## 🔧 Building & consuming
 
-// Brand primitives (aliases)
-colors.primary[500];          // orange palette
-colors.accent[500];           // violet palette
+### Building the package
 
-// Surface primitives (neutral-based)
-colors.surface[950];          // #0a0a0a
-```
+```bash
+# emit both v3 and v4 bundles
+pnpm --filter @aziontech/theme build:tokens
 
-**Semantic tokens** (theme-aware, no `dark:` variant needed):
-```javascript
-// Text colors - automatically switches between light/dark
-colors.text.base;             // neutral-900 (light) / neutral-50 (dark)
-colors.text.muted;            // neutral-600 (light) / neutral-400 (dark)
-colors.text.accent;           // accent-500 (both modes)
-
-// Background colors - theme-aware layers
-colors.background.layer1;     // surface-0 (light) / surface-800 (dark)
-colors.background.layer2;     // surface-50 (light) / surface-700 (dark)
-colors.background.canvas;     // surface-100 (light) / surface-950 (dark)
-
-// Border colors - theme-aware borders
-colors.border.base;           // surface-200 (light) / surface-700 (dark)
-colors.border.primary;        // primary-500 (both modes)
-colors.border.accent;         // accent-500 (both modes)
+# only one target
+pnpm --filter @aziontech/theme build:tokens:v3
+pnpm --filter @aziontech/theme build:tokens:v4
+
+# v3 + compile final CSS with tailwindcss
+pnpm --filter @aziontech/theme build:css:v3
 ```
 
-#### Usage in HTML/Tailwind Classes
-
-**Using semantic tokens** (theme-aware, no `dark:` variant needed):
-```html
-<!-- Semantic background - automatically switches theme -->
-<div class="bg-layer1">
-  Layer 1 background (white in light, dark in dark mode)
-</div>
-
-<!-- Semantic text colors -->
-<p class="text-base">
-  Base text color (auto-adapts to theme)
-</p>
-
-<!-- Semantic borders -->
-<div class="border border-base">
-  Border adapts to current theme
-</div>
-
-<!-- Semantic interactive states -->
-<button class="bg-layer1 hover:bg-layer1-hover border border-primary text-primary">
-  Themed button
-</button>
+Outputs land in `packages/theme/dist/v3/` and `packages/theme/dist/v4/`.
+
+### Consuming in a Tailwind v3 project
+
+```js
+// tailwind.config.js
+import themePreset from '@aziontech/theme/tailwind-preset/v3'
+
+export default {
+  presets: [themePreset],
+  content: ['./src/**/*.{vue,js,ts,jsx,tsx}'],
+  darkMode: ['class'],
+}
 ```
 
-**Using global tokens** (can use `dark:` in this cases):
-```html
-<!-- Background with dark variant -->
-<div class="bg-neutral-50 dark:bg-neutral-950">
-  Adaptive background
-</div>
-
-<!-- Text colors with dark variant -->
-<p class="text-neutral-900 dark:text-neutral-100">
-  Primary text color
-</p>
-
-<!-- Border colors with dark variant -->
-<div class="border border-neutral-200 dark:border-neutral-800">
-  Card with adaptive border
-</div>
-
-<!-- Using brand colors (no dark variant needed) -->
-<button class="bg-orange-500 text-white hover:bg-orange-600">
-  Action Button
-</button>
+```css
+/* main.css */
+@import '@aziontech/theme/v3/globals.css';
 ```
 
-**Available token classes:**
+Utilities like `text-default`, `bg-surface`, `border-default`, `text-primary`, `gap-md`, `p-md`, `.text-heading-lg`, etc. are then available everywhere.
 
-*Global tokens* (use with `dark:` variant):
-- **Neutrals:** `neutral-50` → `neutral-950` (surface backgrounds, text, borders)
-- **Brand:** `orange-50` → `orange-950` (primary actions)
-- **Accent:** `violet-50` → `violet-950` (secondary highlights)
-- **Status:** `red-*`, `green-*`, `yellow-*`, `blue-*` (semantic status colors)
+### Consuming in a Tailwind v4 project
 
-*Semantic tokens* (theme-aware, no `dark:` needed):
-- **Text:** `text-base`, `text-muted`, `text-accent`, `text-primary`, `text-link`
-- **Background:** `bg-layer1`, `bg-layer2`, `bg-canvas`, `bg-base`
-- **Border:** `border-base`, `border-primary`, `border-accent`, `border-warning`, `border-success`, `border-danger`
+```css
+/* main.css */
+@import '@aziontech/theme/v4/globals.css';
+```
 
-### Theme Switch Compatibility
+No `tailwind.config.js` needed — v4 reads `@theme { … }` directly from the imported CSS.
 
-The CSS variable initializer targets both the Tailwind `.dark` class and the existing theme classes used by the SCSS theme:
+### As JS objects (Node / build steps)
 
-```css
-:root, [data-theme=light], .azion.azion-light { /* light vars */ }
-[data-theme=dark], .dark, .azion.azion-dark { /* dark vars */ }
+```js
+import { createCssVars, cssVarsString } from '@aziontech/theme';
+
+createCssVars();   // → { light: { '--text-default': '#1A1A1A', … }, dark: { … } }
+cssVarsString();   // → ':root, [data-theme=light], .azion.azion-light { … } [data-theme=dark], … { … }'
 ```
 
-### Granular Imports (Advanced)
-
-```javascript
-// Named exports for specific token types
-import { 
-  primitives, 
-  brandColors, 
-  brandPrimitives,
-  surfacePrimitives,
-  preset,
-  createTailwindConfig,
-  tokenUtilities 
-} from 'azion-theme/tokens';
+### Injecting at runtime (browser)
+
+```js
+import { injectCssVars } from '@aziontech/theme';
+
+injectCssVars(); // appends a <style data-azion-tokens> element to <head>
 ```
 
-### 🛠️ Sync & Maintenance (With Script)
+Only useful if you can't precompile and import `globals.css` — production usage should prefer the static stylesheet.
+
+---
+
+## ➕ How to add a new token
+
+### Add a new primitive
+
+1. Open the relevant file (e.g., `tokens/primitives/shape/spacing.js`).
+2. Add the key/value:
+
+   ```js
+   export const spacing = {
+     /* … */
+     128: '512px',   // new
+   };
+   ```
+
+3. Rebuild (`pnpm --filter @aziontech/theme build:tokens`). The compiler picks it up and emits `--spacing-128: 512px`.
+
+### Add a new semantic (theme) token
+
+1. Pick the right file (`tokens/theme/*.js` or `tokens/theme/feedback/*.js`).
+2. Add the key with `tokenRef(...)` for both `light` and `dark`:
+
+   ```js
+   // tokens/theme/border.js
+   export const border = {
+     light: {
+       /* … */
+       'border-emphasis': tokenRef('primitives.gray.400'),
+     },
+     dark: {
+       /* … */
+       'border-emphasis': tokenRef('primitives.gray.500'),
+     },
+   };
+   ```
+
+3. Rebuild. The new variable lands in both `:root` and `[data-theme=dark]` blocks.
+
+### Add a new responsive semantic token
+
+1. Add an entry to the relevant `*.data.js` file in `tokens/semantic/`:
+
+   ```js
+   // tokens/semantic/spacings.data.js
+   export const spacingsData = {
+     /* … */
+     'gap-2xl': { _: '32px', md: '40px', xl: '56px' },
+   };
+   ```
+
+2. Rebuild. `build-tokens.mjs` emits the base var in `:root`, per-breakpoint `@media` overrides, **and** a matching `.gap-2xl { gap: var(--gap-2xl) }` utility.
+
+---
 
-#### How to feed new and changed tokens from Figma
+## 🔗 Token references (`tokenRef`)
 
-1) **Update Figma Variables**
-   - Ensure **Global** and **Semantic** variables are updated and organized correctly (naming, groups, modes, and values).
+`tokenRef(path)` returns a marker object `{ __ref: path }` that the compiler resolves at build time. Supported path prefixes (see `scripts/resolve.js`):
 
-2) **Open the Tokens Studio for Figma plugin**
+| Prefix | Looks up |
+|---|---|
+| `primitives.X.Y.Z` | `tokens/primitives/colors/colors.js` tree (e.g., `primitives.gray.900`, `primitives.alpha.orange.100`) |
+| `surfacePrimitives.surface.N` | the surface palette (used internally; usually referenced via `brand.surfaces.…`) |
+| `brand.surfaces.surface-N` | `surfacePrimitives.surface[N]` (e.g., `brand.surfaces.surface-100` → `#F5F5F5`) |
+| `brand.primary.primary-N` | `brandPrimitives.primary[N]` (e.g., `brand.primary.primary-500` → `#FE601F`) |
+| `brand.accent.accent-N` | `brandPrimitives.accent[N]` |
+| `brand.absolute.X` | `brandPrimitives.absolute.X` (`black` / `white`) |
 
-3) **Import Figma Variables into Tokens Studio**
-   - Use Tokens Studio’s import-from-variables flow to bring the current Variables state into the token sets.
+Refs of unknown prefixes are left as the raw path string in the output — flag for "this needs resolver support".
 
-4) **Export to file/folder**
-   - Export using **Multiple files**.
+---
 
-5) **Copy the exported files into this repo**
-   - Place them under [`src/tokens/figma-reference-tokens-studio/`](src/tokens/figma-reference-tokens-studio:1) (replace existing contents).
+## 🧪 Test pages
 
-6) **Regenerate the code tokens**
-   - Run:
+Local visual harnesses (require a static server because of ESM imports):
 
 ```bash
-node ./scripts/figma-sync.js
+npx http-server packages/theme/src -p 8080
 ```
 
-7) **Review and commit**
-   - Inspect the diff in the generated files and validate light/dark semantics before committing.
-
-Files affected by the script:
-- [`src/tokens/primitives/colors.js`](src/tokens/primitives/colors.js)
-- [`src/tokens/primitives/brand.js`](src/tokens/primitives/brand.js)
-- [`src/tokens/semantic/text.js`](src/tokens/semantic/text.js)
-- [`src/tokens/semantic/backgrounds.js`](src/tokens/semantic/backgrounds.js)
-- [`src/tokens/semantic/borders.js`](src/tokens/semantic/borders.js)
-
-### 🧰 Manual Maintenance (Without Script)
-
-When updating or adding tokens manually, edit the files below depending on the token type:
-
-- **Primitive palettes:** [`src/tokens/primitives/colors.js`](src/tokens/primitives/colors.js)
-- **Brand + surface primitives:** [`src/tokens/primitives/brand.js`](src/tokens/primitives/brand.js)
-- **Semantic text (light/dark):** [`src/tokens/semantic/text.js`](src/tokens/semantic/text.js)
-- **Semantic backgrounds (light/dark):** [`src/tokens/semantic/backgrounds.js`](src/tokens/semantic/backgrounds.js)
-- **Semantic borders (light/dark):** [`src/tokens/semantic/borders.js`](src/tokens/semantic/borders.js)
-- **Brand aliases:** [`src/tokens/colors-brand.js`](src/tokens/colors-brand.js)
-- **Tailwind mappings (class names):** [`src/tokens/build/preset.js`](src/tokens/build/preset.js)
-- **CSS vars output/selectors:** [`src/tokens/build/css-vars.js`](src/tokens/build/css-vars.js)
-
-Checklist when adding a new token manually:
-1) Add/update the primitive or surface scale value (if needed).
-2) Add matching semantic entries for both `light` and `dark`.
-3) Update Tailwind mappings if you want a class for the token.
-4) Regenerate or verify CSS vars output for both themes.
-
-### 🎨 Available Colors
-
-#### Main Palette (Orange)
-- `orange-50` → `orange-950`
-- **Primary**: `orange-500` (#fe601f)
-
-#### Brand Palette
-- `brand-black` (#0a0a0a)
-- `brand-white` (#fafafa)
-- `brand-dark-gray` (#171717)
-- `brand-medium-gray` (#737373)
-
-#### Other Complete Palettes
-- **Violet, Slate, Gray, Neutral, Blue, Red, Yellow, Green**
-- All with 11 shades (50 → 950)
-
-#### Semantic Colors
-- `primary` (orange-500)
-- `success` (green-500)
-- `warning` (yellow-500)
-- `error` (red-500)
-- `info` (blue-500)
-
-### ⚠️ Troubleshooting
-
-#### If you get import errors:
-
-**ES Modules (recommended)**
-```javascript
-import colors from 'azion-theme/tokens';
-```
+- `http://localhost:8080/tests/primitives.html` — every primitive rendered as a swatch / scale.
+- `http://localhost:8080/tests/theme.html` — semantic tokens with a **light/dark toggle**.
+- `http://localhost:8080/tests/tokens.html` — combined view.
 
-**Named exports**
-```javascript
-import { primitives, brandColors, brandPrimitives, surfacePrimitives } from 'azion-theme/tokens';
-```
+---
 
-**Direct file imports**
-```javascript
-import { primitives } from 'azion-theme/tokens/primitives/colors.js';
-import { brandColors } from 'azion-theme/tokens/colors-brand.js';
-```
+## 🌗 Theme switching
 
-**Configure Vite (if using Vite)**
-Add to your `vite.config.js`:
-```javascript
-export default {
-  resolve: {
-    conditions: ['import', 'module', 'browser', 'default']
-  }
+The compiled CSS targets multiple hooks so the runtime can pick whichever convention the consumer uses:
+
+```css
+:root, [data-theme=light], .azion.azion-light {
+  /* light theme vars */
+}
+
+[data-theme=dark], .dark, .azion.azion-dark {
+  /* dark theme vars */
 }
 ```
 
+Switching is a one-liner:
+
+```js
+// data-attribute strategy
+document.documentElement.setAttribute('data-theme', 'dark'); // or 'light'
+
+// Tailwind class strategy
+document.documentElement.classList.toggle('dark');
+
+// Azion namespaced classes (use one or the other)
+document.documentElement.classList.add('azion', 'azion-dark');
+```
+
+All three strategies hit the same set of CSS variables.
+
+---
+
 ## 🔗 Links
 
 - [Figma Global Tokens](https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Global-Tokens?node-id=0-1)