shadcn-glass-ui 1.0.11 → 2.0.1

package/docs/TOKEN_ARCHITECTURE.md

@@ -0,0 +1,365 @@
+# Token Architecture Guide
+
+## 3-Layer CSS Token System
+
+The Glass UI library uses a **3-layer token architecture** to eliminate color duplication and enable
+rapid theme creation.
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────┐
+│ Layer 3: Component Tokens                   │
+│ --btn-primary-bg, --input-border, etc.      │
+│ Purpose: Component-specific styling         │
+└─────────────────────────────────────────────┘
+                    ↓ references
+┌─────────────────────────────────────────────┐
+│ Layer 2: Semantic Tokens                    │
+│ --semantic-primary, --semantic-surface      │
+│ Purpose: Role-based, theme-specific         │
+└─────────────────────────────────────────────┘
+                    ↓ references
+┌─────────────────────────────────────────────┐
+│ Layer 1: Primitive Tokens                   │
+│ --oklch-purple-500, --oklch-white-8         │
+│ Purpose: Single source of truth for colors  │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Layer 1: Primitive Tokens
+
+**File:** `src/styles/tokens/oklch-primitives.css`
+
+**Purpose:** Define raw OKLCH color values once, shared across all themes.
+
+**Naming Convention:** `--oklch-{family}-{scale}[-{alpha}]`
+
+**Examples:**
+
+```css
+--oklch-purple-500: oklch(66.6% 0.159 303);
+--oklch-purple-500-30: oklch(66.6% 0.159 303 / 0.3);
+--oklch-white-8: oklch(100% 0 0 / 0.08);
+--oklch-emerald-400: oklch(76.5% 0.147 163);
+```
+
+**Total Primitives:** 207 tokens
+
+- Base colors: ~50 (color families at various scales)
+- Alpha variants: ~157 (commonly-used opacity levels)
+
+**Key Color Families:**
+
+- **Achromatic:** white, black (with 15+ alpha variants each)
+- **Primary:** purple-500 (glass), violet-600 (light), violet-500 (aurora)
+- **Neutral:** slate-100 through slate-950
+- **Status:** emerald (success), amber (warning), rose/red (error), blue (info)
+- **Accent:** cyan, pink
+
+**DO NOT** use primitive tokens directly in components. Use semantic tokens instead.
+
+---
+
+## Layer 2: Semantic Tokens
+
+**File:** Each theme file (glass.css, light.css, aurora.css)
+
+**Purpose:** Map primitive tokens to semantic roles that describe color usage, not appearance.
+
+**Naming Convention:** `--semantic-{role}[-{modifier}]`
+
+**Examples:**
+
+```css
+/* Glass theme */
+--semantic-primary: var(--oklch-purple-500);
+--semantic-surface: var(--oklch-white-8);
+--semantic-text: var(--oklch-white-90);
+
+/* Light theme */
+--semantic-primary: var(--oklch-violet-600);
+--semantic-surface: var(--oklch-slate-100-80);
+--semantic-text: var(--oklch-slate-800);
+```
+
+**Semantic Roles:**
+
+| Role                   | Purpose                  | Example Values         |
+| ---------------------- | ------------------------ | ---------------------- |
+| `--semantic-primary`   | Main accent color        | purple-500, violet-600 |
+| `--semantic-secondary` | Secondary accent         | violet-500             |
+| `--semantic-surface`   | Card/surface backgrounds | white-8, slate-100-80  |
+| `--semantic-border`    | Standard borders         | white-15, slate-200    |
+| `--semantic-text`      | Primary text color       | white-90, slate-800    |
+| `--semantic-success`   | Success states           | emerald-400            |
+| `--semantic-warning`   | Warning states           | amber-400              |
+| `--semantic-error`     | Error states             | rose-400, red-500      |
+| `--semantic-info`      | Info states              | blue-400               |
+
+**Modifiers:**
+
+- `-muted`: Reduced opacity (e.g., `--semantic-primary-muted`)
+- `-subtle`: Very light background (e.g., `--semantic-surface-subtle`)
+- `-elevated`: Higher z-index surfaces (e.g., `--semantic-surface-elevated`)
+- `-text`: Text color variant (e.g., `--semantic-success-text`)
+
+---
+
+## Layer 3: Component Tokens
+
+**File:** Each theme file (glass.css, light.css, aurora.css)
+
+**Purpose:** Component-specific styling variables that reference semantic tokens.
+
+**Naming Convention:** `--{component}-{variant}-{property}`
+
+**Examples:**
+
+```css
+--btn-primary-bg: linear-gradient(135deg, var(--semantic-primary), var(--semantic-secondary));
+--btn-primary-text: var(--semantic-text-inverse);
+--badge-success-bg: var(--semantic-success-subtle);
+--input-border: var(--semantic-border);
+--card-hover-glow: 0 0 20px var(--oklch-purple-500-25);
+```
+
+**Component Groups:**
+
+- Buttons (primary, secondary, ghost, destructive, success)
+- Badges (default, secondary, destructive, success, warning, info)
+- Alerts (default, destructive, success, warning)
+- Inputs (text, focus states)
+- Cards (subtle, medium, strong variants)
+- Status (online, offline, busy, away)
+- Notifications, Tooltips, Modals, Dropdowns, etc.
+
+---
+
+## Benefits of This Architecture
+
+### 1. Single Source of Truth
+
+Change a color once in primitives, affects all themes that use it:
+
+```css
+/* Change primary purple across entire library */
+--oklch-purple-500: oklch(70% 0.16 305); /* Lighter purple */
+```
+
+### 2. Rapid Theme Creation
+
+Create a new theme in ~50 lines by only defining semantic mappings:
+
+```css
+[data-theme='neon'] {
+  --semantic-primary: var(--oklch-cyan-400);
+  --semantic-surface: var(--oklch-black-90);
+  /* ... 15 more semantic tokens */
+  /* Component tokens inherited automatically! */
+}
+```
+
+### 3. Type Safety
+
+Semantic names prevent confusion:
+
+```css
+/* ❌ Bad: What does this represent? */
+--btn-bg: oklch(66.6% 0.159 303);
+
+/* ✅ Good: Clear semantic meaning */
+--btn-primary-bg: var(--semantic-primary);
+```
+
+### 4. Maintainability
+
+- **Before:** 98 hardcoded OKLCH values in glass.css
+- **After:** 0 hardcoded values, all use tokens
+- **Result:** Change theme colors in seconds, not hours
+
+### 5. Consistency
+
+All components using `--semantic-primary` automatically stay in sync when theme changes.
+
+---
+
+## Migration Results
+
+| Metric                     | Before    | After                     | Improvement                  |
+| -------------------------- | --------- | ------------------------- | ---------------------------- |
+| Unique color values        | ~120      | 207 primitives (reusable) | 75% reduction in duplication |
+| Glass.css hardcoded OKLCH  | 98        | 0                         | 100% elimination             |
+| Light.css hardcoded OKLCH  | ~100      | 0                         | 100% elimination             |
+| Aurora.css hardcoded OKLCH | ~80       | 0                         | 100% elimination             |
+| Theme creation time        | 2-3 hours | 10-15 minutes             | **90% faster**               |
+
+---
+
+## Usage Examples
+
+### Example 1: Using Semantic Tokens in Components
+
+```tsx
+// In component styles (CSS/Tailwind)
+.my-card {
+  background: var(--semantic-surface);
+  border: 1px solid var(--semantic-border);
+  color: var(--semantic-text);
+}
+
+.my-card:hover {
+  background: var(--semantic-surface-elevated);
+  border-color: var(--semantic-primary);
+}
+```
+
+### Example 2: Creating a New Component Token
+
+```css
+/* Add to theme file (glass.css, light.css, etc.) */
+--my-widget-bg: var(--semantic-surface);
+--my-widget-border: var(--semantic-border-strong);
+--my-widget-accent: var(--semantic-primary);
+--my-widget-hover-glow: 0 0 20px var(--oklch-purple-500-30);
+```
+
+### Example 3: Override for Specific Theme
+
+```css
+/* glass.css */
+--metric-card-glow: 0 0 12px var(--oklch-purple-500-40);
+
+/* light.css */
+--metric-card-glow: none; /* No glow in light theme */
+```
+
+---
+
+## Best Practices
+
+### DO ✅
+
+1. **Always use semantic tokens in component tokens:**
+
+   ```css
+   --btn-primary-bg: var(--semantic-primary);
+   ```
+
+2. **Use primitive tokens for specific effects:**
+
+   ```css
+   --btn-primary-glow: 0 0 30px var(--oklch-purple-500-60);
+   ```
+
+3. **Create semantic tokens for new color roles:**
+
+   ```css
+   --semantic-accent-secondary: var(--oklch-cyan-500);
+   ```
+
+4. **Document new semantic tokens:**
+   ```css
+   /* Accent for promotional badges */
+   --semantic-promo: var(--oklch-pink-500);
+   ```
+
+### DON'T ❌
+
+1. **Don't hardcode OKLCH values:**
+
+   ```css
+   /* ❌ Bad */
+   --btn-bg: oklch(66.6% 0.159 303);
+
+   /* ✅ Good */
+   --btn-bg: var(--semantic-primary);
+   ```
+
+2. **Don't use primitive tokens in component styles:**
+
+   ```css
+   /* ❌ Bad */
+   .card {
+     background: var(--oklch-white-8);
+   }
+
+   /* ✅ Good */
+   .card {
+     background: var(--semantic-surface);
+   }
+   ```
+
+3. **Don't skip semantic layer:**
+
+   ```css
+   /* ❌ Bad (skips semantic layer) */
+   --btn-primary-bg: var(--oklch-purple-500);
+
+   /* ✅ Good (uses semantic layer) */
+   --btn-primary-bg: var(--semantic-primary);
+   ```
+
+4. **Don't create semantic tokens without documenting them:**
+
+   ```css
+   /* ❌ Bad: What is this for? */
+   --semantic-special: var(--oklch-pink-500);
+
+   /* ✅ Good: Clear purpose */
+   /* Premium badge accent color */
+   --semantic-premium: var(--oklch-pink-500);
+   ```
+
+---
+
+## File Locations
+
+```
+src/styles/
+├── tokens/
+│   └── oklch-primitives.css    # Layer 1: Primitive tokens (207 tokens)
+└── themes/
+    ├── glass.css                # Layer 2 + 3: Semantic + Component (glass theme)
+    ├── light.css                # Layer 2 + 3: Semantic + Component (light theme)
+    └── aurora.css               # Layer 2 + 3: Semantic + Component (aurora theme)
+```
+
+---
+
+## Related Documentation
+
+- [THEME_CREATION_GUIDE.md](./THEME_CREATION_GUIDE.md) - Step-by-step guide to creating new themes
+- [PRIMITIVE_MAPPING.md](./PRIMITIVE_MAPPING.md) - Complete mapping of OKLCH values to primitives
+- [CSS_VARIABLES_REFACTORING_PLAN.md](./CSS_VARIABLES_REFACTORING_PLAN.md) - Original refactoring
+  plan
+
+---
+
+## Browser Compatibility
+
+**Primitive Tokens:** Universal support (CSS custom properties)
+
+**OKLCH Colors:** Modern browsers only
+
+- Chrome 111+ (March 2023)
+- Safari 15.4+ (March 2022)
+- Firefox 113+ (May 2023)
+
+**Fallback Strategy:** Explicit OKLCH values defined (no `oklch(from ...)` relative colors used)
+
+---
+
+## Contributing
+
+When adding new colors or components:
+
+1. Check if needed primitive exists in `oklch-primitives.css`
+2. If not, add to appropriate color family section
+3. Create semantic mapping in theme files
+4. Document new semantic tokens with comments
+5. Test across all 3 themes (glass, light, aurora)