azion-theme ยท tokens
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:
- **`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`.
Tokens live in JS as the source-of-truth and are compiled at package build time, not in the browser.
## ๐ 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)
---
## ๐ Architecture overview
Three layers:
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`.
Compile pipeline:
```
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)
```
- 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.
---
## ๐ File structure
```
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
```
---
## ๐จ Token types
### Primitives
Plain JS objects with literal values. Theme-invariant.
```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' }
}
```
```js
// tokens/primitives/shape/spacing.js
export const spacing = { 1: '4px', 2: '8px', /* โฆ */ 96: '384px' }
```
### Semantic / theme
Objects with `light` / `dark` variants. Values are `tokenRef(...)` calls that point to primitives.
```js
// tokens/theme/primary.js
import { tokenRef } from '../../scripts/refs.js'
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')
}
}
```
### Responsive semantic data (`*.data.js`)
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`).
```js
// tokens/semantic/spacings.data.js
export const spacingsData = {
'gap-sm': { _: '8px', md: '12px', xl: '16px' },
'gap-md': { _: '12px', md: '16px', xl: '24px' }
// โฆ
}
```
`_` is the base value emitted in `:root`; the breakpoint keys (`sm`, `md`, `lg`, `xl`, `2xl`) become media-query overrides.
---
## ๐ง Building & consuming
### Building the package
```bash
# emit the v4 bundle
pnpm --filter @aziontech/theme build:tokens
```
Output lands in `packages/theme/dist/v4/`.
### Consuming (Tailwind v4)
```css
/* main.css */
@import '@aziontech/theme/globals.css';
```
No `tailwind.config.js` needed โ v4 reads `@theme { โฆ }` directly from the imported CSS.
Utilities like `text-default`, `bg-surface`, `border-default`, `text-primary`, `gap-md`, `p-md`, `.text-heading-lg`, `animate-popup-scale-in`, etc. are then available everywhere.
### As JS objects (Node / build steps)
```js
import { createCssVars, cssVarsString } from '@aziontech/theme'
createCssVars() // โ { light: { '--text-default': '#1A1A1A', โฆ }, dark: { โฆ } }
cssVarsString() // โ ':root, [data-theme=light], .azion.azion-light { โฆ } [data-theme=dark], โฆ { โฆ }'
```
### Injecting at runtime (browser)
```js
import { injectCssVars } from '@aziontech/theme'
injectCssVars() // appends a