diff --git a/packages/theme/README.md b/packages/theme/README.md
index ab662b3d2..f75660ae0 100644
--- a/packages/theme/README.md
+++ b/packages/theme/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,210 @@ 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
-
-
-
-
-
-
-
-
+```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
+
+
+
+
+
+
+
```
-### Option 4: CSS Variables Injection
-
-Inject CSS variables dynamically at runtime:
-
```javascript
-import { injectCssVars } from '@aziontech/theme/tokens'
-
-// Injects