@aziontech/theme 4.2.0 → 4.3.1

package/README.md

@@ -1,15 +1,8 @@
 # @aziontech/theme
 
-A comprehensive design token system and theming solution for Azion's web applications. This package provides primitive colors, semantic tokens, brand colors, and seamless integration with Tailwind CSS.
+Azion's design-token system, compiled into a single **Tailwind CSS v4** stylesheet: primitive palettes, brand colors, light/dark semantic tokens, the full text-style scale, motion utilities and `@keyframes`, and the `@font-face` set — plus the raw token data as importable JavaScript.
 
-## Features
-
-- **Design Tokens**: Primitives and Semantic Colors tokens generated from Figma Variables;
-- **Brand Colors**: Azion's official color palette with primary (orange), accent (violet), and surface colors;
-- **Theme Support**: Built-in light and dark mode theming;
-- **Tailwind Integration**: Plugin and preset for seamless Tailwind CSS integration;
-- **CSS Variables**: Automatic CSS variable generation for dynamic theming;
-- **Widget Support**: Separate theme variant for embedded widgets;
+The package ships one prebuilt artifact (`dist/v4/globals.css`) and four small JS entry points. There is no Tailwind preset, plugin, or `tailwind.config.js` step — v4 reads the `@theme` / `@utility` definitions directly from the imported CSS.
 
 ## Installation
 
@@ -21,429 +14,211 @@ pnpm add @aziontech/theme
 yarn add @aziontech/theme
 ```
 
-## Quick Start
-
-### Option 1: CSS Import (Recommended for web applications)
+Tailwind CSS v4 must be present in the consuming build — the stylesheet begins with `@import "tailwindcss"`.
 
-Import the main theme stylesheet:
+## Quick start
 
-```javascript
-// Default theme (includes light/dark mode support)
-import '@aziontech/theme'
-```
+### 1. Import the stylesheet
 
-Add the theme class to your root element:
+In your app's root CSS:
 
-```html
-<div class="azion">
-  <!-- Your application content -->
-</div>
-
-<!-- For dark mode -->
-<div class="azion azion-dark">
-  <!-- Your application content -->
-</div>
+```css
+@import '@aziontech/theme';
 ```
 
-### Option 2: Tailwind CSS Integration
-
-#### Using the Preset
-
-Add the preset to your `tailwind.config.js`:
+or from JavaScript (Vite and friends):
 
 ```javascript
-import { preset } from '@aziontech/theme/tokens'
-
-export default {
-  presets: [preset]
-  // your config
-}
+import '@aziontech/theme'
 ```
 
-#### Using the Plugin
-
-For static utility classes with light/dark mode support:
+That single import provides:
 
-```javascript
-import { tokenUtilities } from '@aziontech/theme/tokens'
-
-export default {
-  plugins: [
-    tokenUtilities({
-      darkSelector: '.dark',
-      extraDarkSelectors: ['.azion.azion-dark']
-    })
-  ]
-}
-```
+- the `@font-face` declarations for the Azion type system (no separate font imports needed);
+- every primitive CSS variable (colors, spacing, shape, typography, effects, breakpoints);
+- the semantic light/dark variables (`--primary`, `--text-default`, `--surface-0`…);
+- text-style utilities (`text-heading-2xl`, `text-big-number-md`, …) with responsive sizes;
+- animation utilities and their `@keyframes` (consumers pair every motion class with a `motion-reduce:` fallback).
 
-### Option 3: JavaScript Token Access
+### 2. Switch themes
 
-Access tokens programmatically:
+Light is the default (`:root`). Dark mode activates on any of these hooks:
 
-```javascript
-// Import all tokens
-import {
-  primitives,
-  brandPrimitives,
-  surfacePrimitives,
-  textSemantic,
-  backgroundSemantic,
-  borderSemantic
-} from '@aziontech/theme/tokens'
-
-// Use primitive colors
-const primaryColor = primitives.orange['500'] // '#fe601f'
-const accentColor = primitives.violet['500'] // '#8a84ec'
-
-// Use semantic tokens (returns token references)
-const textColor = textSemantic.light.textColorBase // tokenRef('primitives.neutral.900')
+```html
+<html data-theme="dark">
+  <!-- or -->
+  <body class="dark">
+    <!-- or the legacy pair -->
+    <div class="azion azion-dark"></div>
+  </body>
+</html>
 ```
 
-### Option 4: CSS Variables Injection
-
-Inject CSS variables dynamically at runtime:
-
 ```javascript
-import { injectCssVars } from '@aziontech/theme/tokens'
-
-// Injects <style data-azion-tokens> into document.head
-const styleElement = injectCssVars()
+// Toggle at runtime
+document.documentElement.dataset.theme = 'dark' // or 'light'
 ```
 
-## Token Structure
+Light-mode selectors: `:root`, `[data-theme='light']`, `.azion.azion-light`.
+Dark-mode selectors: `[data-theme='dark']`, `.dark`, `.azion.azion-dark`.
 
-### Primitive Colors
+## Exports
 
-Base color palettes with numeric scales (50-950):
+The entire public surface, from `package.json#exports`:
 
-```javascript
-import { primitives } from '@aziontech/theme/tokens'
-
-primitives.orange['500'] // Primary brand color
-primitives.violet['500'] // Accent brand color
-primitives.neutral['900'] // Dark surfaces
-primitives.neutral['50'] // Light surfaces
-```
+| Path                            | What it is                                                                 |
+| ------------------------------- | -------------------------------------------------------------------------- |
+| `@aziontech/theme`              | the compiled stylesheet (`dist/v4/globals.css`)                            |
+| `@aziontech/theme/colors`       | color primitives: `primitives`, `brandPrimitives`, `surfacePrimitives`     |
+| `@aziontech/theme/animations`   | motion primitives: `animate`, `curve`, `duration`, `useWhen`               |
+| `@aziontech/theme/texts`        | `textsData` — font-size/line-height/weight bundles per text style          |
+| `@aziontech/theme/theme-colors` | semantic compiler: `compileThemeVars`, `compileThemeCss`, `injectThemeCss` |
 
-Available primitives:
+## JavaScript token access
 
-- `base`: White and black
-- `orange`: Primary brand color (11 shades)
-- `violet`: Accent brand color (11 shades)
-- `neutral`: Gray scale for surfaces (11 shades)
-- `gray`, `slate`: Additional gray variants
-- `red`: Semantic danger color
-- `green`: Semantic success color
-- `yellow`: Semantic warning color
-- `blue`: Link colors
-
-### Brand Primitives
-
-Azion-specific brand colors:
+### Color primitives
 
 ```javascript
-import { brandPrimitives } from '@aziontech/theme/tokens'
+import { primitives, brandPrimitives, surfacePrimitives } from '@aziontech/theme/colors'
 
-brandPrimitives.primary['500'] // Orange brand color
-brandPrimitives.accent['500'] // Violet accent color
-brandPrimitives.absolute.white // Pure white
-brandPrimitives.absolute.black // Pure black
-```
+primitives.orange[500] // '#F3652B' — primary brand
+primitives.blue[500] // '#0072F5' — accent
+primitives.violet[500] // '#8A84EC' — brand.accent palette
+primitives.gray[900] // '#141414'
 
-### Surface Primitives
+brandPrimitives.primary[500] // '#F3652B'
+brandPrimitives.absolute.white // '#FFFFFF'
 
-Surface color scales for backgrounds:
-
-```javascript
-import { surfacePrimitives } from '@aziontech/theme/tokens'
-
-surfacePrimitives.surface['0'] // White
-surfacePrimitives.surface['50'] // Lightest gray
-surfacePrimitives.surface['900'] // Very dark gray
-surfacePrimitives.surface['950'] // Almost black
+surfacePrimitives.surface[0] // '#FFFFFF'
+surfacePrimitives.surface[950] // '#0A0A0A'
 ```
 
-### Semantic Tokens
+Available palettes: `base`, `blue`, `gray`, `slate`, `orange`, `violet`, `yellow`, `green`, `red` — plus the `brand`, `surface`, and `alpha` groups.
 
-Context-aware tokens that automatically adapt to light/dark themes:
-
-#### Background Tokens
+### Motion primitives
 
 ```javascript
-import { backgroundSemantic } from '@aziontech/theme/tokens'
-
-// Light mode
-backgroundSemantic.light.bgLayer1 // Surface 0 (white)
-backgroundSemantic.light.bgLayer2 // Surface 50
-backgroundSemantic.light.bgCanvas // Surface 100
+import { curve, duration, animate } from '@aziontech/theme/animations'
 
-// Dark mode
-backgroundSemantic.dark.bgLayer1 // Surface 800
-backgroundSemantic.dark.bgCanvas // Surface 950
+curve['productive-exit'] // easing cubic-bezier
+duration['fast-02'] // ms value
+animate.shimmer // keyframe-backed animation definition
 ```
 
-#### Text Tokens
+### Text styles
 
 ```javascript
-import { textSemantic } from '@aziontech/theme/tokens'
-
-// Light mode
-textSemantic.light.textColorBase // neutral.900
-textSemantic.light.textColorMuted // neutral.600
-textSemantic.light.textColorLink // blue.600
-
-// Dark mode
-textSemantic.dark.textColorBase // neutral.50
-textSemantic.dark.textColorMuted // neutral.400
-textSemantic.dark.textColorLink // blue.300
-```
-
-#### Border Tokens
-
-```javascript
-import { borderSemantic } from '@aziontech/theme/tokens'
-
-borderSemantic.light.borderBase // surface.200
-borderSemantic.light.borderPrimary // primary.500
-borderSemantic.light.borderDanger // red.600
-
-borderSemantic.dark.borderBase // surface.700
-borderSemantic.dark.borderDanger // red.400
-```
-
-## Theming
+import { textsData } from '@aziontech/theme/texts'
 
-### Light Mode (Default)
-
-```html
-<div class="azion azion-light">
-  <!-- Light theme content -->
-</div>
+textsData['text-heading-2xl']
+// { fontSize: { _: '1.875rem', sm: '3rem', md: '3.5rem' }, lineHeight: 1.25, fontWeight: 400 }
 ```
 
-### Dark Mode
-
-```html
-<div class="azion azion-dark">
-  <!-- Dark theme content -->
-</div>
-```
+Responsive `fontSize` keys (`_`, `sm`, `md`, …) become `@media (min-width: …)` overrides in the compiled utilities.
 
-Or use the standard Tailwind dark mode class:
-
-```html
-<div class="azion dark">
-  <!-- Dark theme content -->
-</div>
-```
-
-### Dynamic Theme Switching
+### Semantic variables as JS (Node / build steps / runtime)
 
 ```javascript
-// Toggle dark mode
-const root = document.querySelector('.azion')
-root.classList.toggle('azion-dark')
-root.classList.toggle('azion-light')
-```
+import { compileThemeVars, compileThemeCss, injectThemeCss } from '@aziontech/theme/theme-colors'
 
-## Tailwind CSS Usage
+compileThemeVars()
+// → { light: { '--primary': '#F3652B', '--text-default': '#141414', … }, dark: { … } }
 
-### With Preset (Dynamic CSS Variables)
+compileThemeCss()
+// → ':root, [data-theme=light], .azion.azion-light { … }\n\n[data-theme=dark], .dark, … { … }'
 
-```html
-<!-- Background colors -->
-<div class="bg-layer1">Layer 1 background</div>
-<div class="bg-canvas">Canvas background</div>
-<div class="bg-base">Base background</div>
-
-<!-- Text colors -->
-<p class="text-base">Base text</p>
-<p class="text-muted">Muted text</p>
-<a class="text-link">Link text</a>
-
-<!-- Border colors -->
-<div class="border border-base">Default border</div>
-<div class="border border-primary">Primary border</div>
+injectThemeCss() // appends a <style data-azion-theme> element to <head>
 ```
 
-### With Plugin (Static Utilities)
+Only useful when you can't precompile — production usage should prefer the static stylesheet.
 
-When using the `tokenUtilities` plugin:
+## CSS variables
 
-```html
-<!-- These generate static values for both light and dark -->
-<div class="bg-layer1">Light: white / Dark: surface-800</div>
-<div class="text-base">Light: neutral-900 / Dark: neutral-50</div>
-```
-
-### Complete Tailwind Config Example
-
-```javascript
-import { preset, tokenUtilities } from '@aziontech/theme/tokens'
-
-export default {
-  content: ['./src/**/*.{js,ts,jsx,tsx}'],
-  presets: [preset],
-  darkMode: 'class',
-  plugins: [
-    tokenUtilities({
-      darkSelector: '.dark',
-      extraDarkSelectors: ['.azion.azion-dark']
-    })
-  ]
-}
-```
-
-## CSS Variables
-
-All semantic tokens are available as CSS variables:
+The semantic layer flips automatically between modes:
 
 ```css
-/* Automatically generated */
 :root,
 [data-theme='light'],
 .azion.azion-light {
-  --text-default: #171717;
-  --text-muted: #525252;
-  --background-surface: #ffffff;
-  --border-default: #e5e5e5;
+  --primary: #f3652b;
+  --text-default: #141414;
+  /* … */
 }
 
 [data-theme='dark'],
 .dark,
 .azion.azion-dark {
   --text-default: #fafafa;
-  --text-muted: #a3a3a3;
-  --background-surface: #262626;
-  --border-default: #404040;
+  /* … */
 }
 ```
 
-Use in your CSS:
+Use them directly:
 
 ```css
 .custom-component {
   color: var(--text-default);
-  background-color: var(--background-surface);
-  border-color: var(--border-default);
+  border-color: var(--primary);
 }
 ```
 
-## Widget Theme
-
-For embedded widgets and iframes, use the widget theme variant:
-
-```javascript
-import '@aziontech/theme/widget'
-```
-
-The widget theme includes:
-
-- Compact variable definitions
-- Optimized for isolated contexts
-- Same token structure as main theme
-
-## API Reference
+Utility equivalents are generated in the same stylesheet (e.g. `@utility text-default`), so `class="text-default"` works wherever Tailwind runs.
 
-### Exports
-
-#### Default Export
-
-- `@aziontech/theme` - Main CSS theme (default.js)
-- `@aziontech/theme/widget` - Widget CSS theme (widget.js)
-- `@aziontech/theme/tokens` - JavaScript token system (src/tokens/index.js)
-
-#### Token Exports
-
-```javascript
-// Primitive tokens
-export { primitives } from './primitives/colors.js'
-export { brandPrimitives, surfacePrimitives } from './primitives/brand.js'
-
-// Semantic tokens
-export { textSemantic } from './semantic/text.js'
-export { backgroundSemantic } from './semantic/backgrounds.js'
-export { borderSemantic } from './semantic/borders.js'
-
-// Build utilities
-export { tokenRef } from './build/refs.js'
-export { resolveRefsToCssVars } from './build/resolve.js'
-export { createCssVars, cssVarsString, injectCssVars } from './build/css-vars.js'
-export { preset } from './build/preset.js'
-export { tokenUtilities } from './build/tailwind-plugin'
-```
-
-## Token Resolution
+## Token resolution
 
 Tokens use a reference system for maintainability:
 
 ```javascript
 // Define token reference
-const textColor = tokenRef('primitives.neutral.900')
-
-// Resolve to actual value
-resolveRefsToCssVars({
-  primitives,
-  textSemantic
-})
-// Output: { '--text-textColorBase': '#171717' }
-```
-
-## Development
+const textColor = tokenRef('primitives.gray.900')
 
-### Prerequisites
+// The compilers (scripts/compile-primitives.js, scripts/compile-theme.js)
+// resolve refs to literal values at build time — and throw, listing every
+// miss, if a ref does not resolve.
+compileThemeVars()
+// Output: { light: { '--text-default': '#141414', … }, dark: { … } }
+```
 
-- Node.js (LTS version)
-- pnpm (v9+)
+The full reference — supported `tokenRef` prefixes, the build pipeline, how to add a token — lives in [`src/tokens/README.md`](./src/tokens/README.md).
 
-### Scripts
+## Development
 
 ```bash
-# Format code
-pnpm format
-
-# Dry-run package
-pnpm pack:dry
-
-# Publish (requires dist build)
-pnpm publish
+pnpm build:tokens # node src/scripts/build-tokens.mjs → dist/v4/globals.{css,scss}
+pnpm build:dts    # vue-tsc --declaration (emit .d.ts next to sources)
+pnpm format       # prettier over scripts/ and src/
+pnpm pack:dry     # inspect the tarball contents
 ```
 
-### Project Structure
+`dist/` is committed, and `prepack` reruns `build:tokens` + `build:dts` — every publish rebuilds the artifact from source, so a stale or hand-edited `dist/` can never ship.
+
+### Project structure
 
 ```
 packages/theme/
-├── default.js              # Main entry point
-├── widget.js               # Widget entry point
+├── tokens.js                    # in-repo JS barrel (not shipped — use the subpath exports)
 ├── src/
-│   ├── azion/             # CSS theme files
-│   │   ├── theme.scss     # Main theme
-│   │   ├── theme-widget.scss
-│   │   ├── _variables.scss
-│   │   ├── _fonts.scss
-│   │   ├── theme-base/    # Base components
-│   │   ├── extended-components/
-│   │   └── custom/
-│   └── tokens/            # JavaScript tokens
-│       ├── index.js       # Public API
-│       ├── primitives/    # Base colors
-│       ├── semantic/      # Context-aware tokens
-│       └── build/         # Build utilities
-│           ├── preset.js
-│           ├── css-vars.js
-│           └── tailwind-plugin
+│   ├── tokens/
+│   │   ├── primitives/          # colors (brand/surface/alpha), typography, shape, effects, animations, …
+│   │   ├── semantic/            # texts/containers/spacings/z-indices data + semantic color refs
+│   │   ├── theme/               # light/dark semantic groups (primary, background, text, ring, feedback/…)
+│   │   └── README.md            # in-depth token documentation
+│   └── scripts/
+│       ├── refs.js              # tokenRef + isTokenRef + assertResolvedRefs
+│       ├── compile-primitives.js
+│       ├── compile-theme.js     # exported as ./theme-colors
+│       └── build-tokens.mjs     # main entrypoint: emits dist/v4
+├── dist/v4/globals.css          # the shipped stylesheet (committed; rebuilt on publish)
 └── package.json
 ```
 
-## Browser Support
+## Browser support
 
-- Modern browsers with CSS Variables support
-- Chrome, Firefox, Safari, Edge (latest versions)
+Modern evergreen browsers with CSS custom-properties support (Chrome, Firefox, Safari, Edge).
 
 ## Versioning
 
-This package follows [Semantic Versioning](https://semver.org/). Version numbers are automatically managed via semantic-release.
+This package follows [Semantic Versioning](https://semver.org/). Versions are managed by [release-please](https://github.com/googleapis/release-please): merges to `main` update a Release PR, and merging that Release PR cuts the version and publishes.
 
 ## Contributing