From 23d93cb65de05a300f58695fa88962c5bda276d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Isaque=20B=C3=B6ck?= Date: Wed, 20 May 2026 17:31:50 -0300 Subject: [PATCH] docs(theme): rewrite tokens README to match build-tokens pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README still described the older inject-from-browser pipeline (compile-primitives + compile-theme as the entrypoints) and was out of sync with the file tree. Update it to reflect: - The package now ships dist/v3 (tailwind preset + globals.css) and dist/v4 (CSS-first @theme) artifacts emitted by build-tokens.mjs. - Primitives tree includes animations/, more typography (font-weight, leading, tracking), more effects (drop-shadow, inset-shadow, perspective, shadow), and the colors palette no longer has 'neutral' (removed in bcf7cb4 — gray took over). - Both tokens/theme/ and tokens/semantic/ exist; semantic includes the responsive *.data.js tables consumed by build-tokens.mjs. - Documents how to consume the package in Tailwind v3 (preset + globals.css) and v4 (@import globals.css). - Adds 'responsive semantic token' workflow. - Updates tokenRef path table to match the resolver in scripts/resolve.js (surfacePrimitives entry; primitives.gray references). - Lists tests/tokens.html alongside primitives.html and theme.html. - Describes the three theme-switching strategies the emitted CSS supports (data-theme attr, .dark class, azion-* namespace). --- packages/theme/src/tokens/README.md | 244 ++++++++++++++++++---------- 1 file changed, 160 insertions(+), 84 deletions(-) diff --git a/packages/theme/src/tokens/README.md b/packages/theme/src/tokens/README.md index edd2b651..586362c5 100644 --- a/packages/theme/src/tokens/README.md +++ b/packages/theme/src/tokens/README.md @@ -1,13 +1,18 @@

azion-theme · tokens

-Design tokens organized as JavaScript modules, ready to be compiled into CSS custom properties. Architecture targets **Tailwind CSS v4** (CSS-first `@theme` / single stylesheet) — tokens live in JS as the source-of-truth and are compiled to CSS variables at build time. +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) -- [Compile & inject](#-compile--inject) +- [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) @@ -17,23 +22,31 @@ Design tokens organized as JavaScript modules, ready to be compiled into CSS cus ## 🏗 Architecture overview -Two layers: +Three layers: -1. **Primitives** — raw, theme-invariant values (color hexes, px sizes, font sizes, etc.). -2. **Theme (semantic)** — light/dark variants that **reference** primitives via `tokenRef(...)`. +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/*.js ─┐ - ├─► scripts/compile-primitives.js ─► :root { --color-… --size-… } -tokens/theme/*.js ─┘ (single block — values don't change) - └─► scripts/compile-theme.js ─► :root, [data-theme=light] { … } - [data-theme=dark] { … } +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 are **absolute** and emit one block (`:root, [data-theme=light]`). -- Theme tokens have **light** and **dark** variants and emit two blocks. Only theme vars flip between themes. +- 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. --- @@ -44,52 +57,75 @@ src/ ├── tokens/ │ ├── primitives/ │ │ ├── colors/ -│ │ │ ├── colors.js # base, gray, violet, orange, slate, yellow, -│ │ │ │ # green, blue, neutral, red, surface (+ brand, alpha) -│ │ │ ├── brand.js # primary, accent, absolute (brand 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 … 3xl, full +│ │ │ ├── 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, code, display +│ │ │ ├── font-family.js # sans, mono, code │ │ │ ├── font-size.js # text-xs … text-9xl -│ │ │ └── line-height.js # leading-none, leading-3 … leading-10 +│ │ │ ├── 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 -│ │ │ └── opacity.js # opacity-25/50/75/100 +│ │ │ ├── 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 # ring-offset +│ │ └── ring-offset.js │ ├── theme/ -│ │ ├── primary.js # primary, primary-mask/selected/hover/active/contrast -│ │ ├── secondary.js # secondary, secondary-* -│ │ ├── accent.js # accent, accent-* -│ │ ├── surfaces.js # surface-0 … surface-950 (aliases for gray) +│ │ ├── 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, border-muted, border-strong, border-selected +│ │ ├── border.js # border-default/muted/strong/selected │ │ ├── text.js # text-default, text-muted │ │ ├── ring.js # ring-color │ │ └── feedback/ -│ │ ├── success.js # success, success-border, success-contrast +│ │ ├── success.js │ │ ├── warning.js │ │ ├── danger.js │ │ └── info.js -│ └── semantic/ # legacy semantic colors (pre-v4 pipeline) -│ └── colors.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 -│ ├── resolve.js # legacy resolver (semantic/colors.js) -│ ├── css-vars.js # legacy CSS-vars compiler -│ ├── compile-primitives.js # NEW: flattens primitives → :root -│ └── compile-theme.js # NEW: resolves theme refs → :root + [data-theme=dark] +│ ├── 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 # visual harness with light/dark toggle + ├── theme.html # semantic tokens with light/dark toggle + └── tokens.html # combined view ``` --- @@ -102,7 +138,7 @@ Plain JS objects with literal values. Theme-invariant. ```js // tokens/primitives/colors/brand.js -export const brand = { +export const brandPrimitives = { primary: { 50: '#FFF5EF', 100: '#FFE7D8', /* … */ 500: '#FE601F', /* … */ 950: '#401602' }, accent: { 50: '#F6F6FF', /* … */ 500: '#8A84EC', /* … */ 950: '#0B0A19' }, absolute: { black: '#0A0A0A', white: '#FCFCFC' }, @@ -114,9 +150,9 @@ export const brand = { export const spacing = { 1: '4px', 2: '8px', /* … */ 96: '384px' }; ``` -### Theme (semantic) +### Semantic / theme -Objects with `light` / `dark` variants. Values are `tokenRef(...)` calls that point to primitives (or to other semantic tokens like `theme.surfaces.surface-X`). +Objects with `light` / `dark` variants. Values are `tokenRef(...)` calls that point to primitives. ```js // tokens/theme/primary.js @@ -138,53 +174,89 @@ export const primary = { }; ``` +### 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. + --- -## 🔧 Compile & inject +## 🔧 Building & consuming + +### Building the package + +```bash +# emit both v3 and v4 bundles +pnpm --filter @aziontech/theme build:tokens + +# 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 +``` + +Outputs land in `packages/theme/dist/v3/` and `packages/theme/dist/v4/`. -### In the browser +### Consuming in a Tailwind v3 project ```js -import { injectPrimitivesCss } from '@aziontech/theme/scripts/compile-primitives.js'; -import { injectThemeCss } from '@aziontech/theme/scripts/compile-theme.js'; +// tailwind.config.js +import themePreset from '@aziontech/theme/tailwind-preset/v3' -injectPrimitivesCss(); //