shadcn-glass-ui 1.0.11 → 2.0.0

package/docs/CSS_VARIABLES_AUDIT.md

@@ -0,0 +1,306 @@
+# CSS Variables Audit & Optimization Report
+
+## 📊 Summary
+
+**Total CSS Variables:**
+
+- Glass theme: 296 variables
+- Light theme: 288 variables
+- Aurora theme: 288 variables
+
+**Status:** ✅ All deprecated aliases (`metric-emerald-*`, `metric-amber-*`, `metric-blue-*`,
+`metric-red-*`) are **only used in CSS definitions** for backward compatibility. **No usage in
+components or tests.**
+
+---
+
+## 🔍 Findings
+
+### 1. ✅ Deprecated Variables Usage: CLEAN
+
+**Result:** No deprecated variable usage found in production code.
+
+- ❌ `--metric-emerald-*` - Not used in components
+- ❌ `--metric-amber-*` - Not used in components
+- ❌ `--metric-blue-*` - Not used in components
+- ❌ `--metric-red-*` - Not used in components
+
+All components successfully migrated to:
+
+- ✅ `--metric-success-*`
+- ✅ `--metric-warning-*`
+- ✅ `--metric-default-*`
+- ✅ `--metric-destructive-*`
+
+**Deprecated aliases remain only in CSS files** (glass.css, light.css, aurora.css) for backward
+compatibility with external consumers.
+
+---
+
+### 2. 🎯 Duplicate Patterns Found
+
+#### A. `transparent` Background Variables (19 occurrences in Glass)
+
+**All these variables = `transparent` across all themes:**
+
+```css
+/* Buttons */
+--btn-ghost-bg: transparent;
+
+/* Badges */
+--badge-default-border: transparent;
+--badge-secondary-border: transparent;
+--badge-destructive-border: transparent;
+--badge-outline-bg: transparent;
+--badge-success-border: transparent;
+--badge-warning-border: transparent;
+--badge-info-border: transparent;
+
+/* Tabs */
+--tab-bg: transparent;
+
+/* Metrics */
+--metric-default-bg: transparent;
+--metric-default-border: transparent;
+--metric-secondary-bg: transparent;
+--metric-secondary-border: transparent;
+--metric-success-bg: transparent;
+--metric-success-border: transparent;
+--metric-warning-bg: transparent;
+--metric-warning-border: transparent;
+--metric-destructive-bg: transparent;
+--metric-destructive-border: transparent;
+```
+
+#### B. `none` Glow Variables (14 occurrences in Light theme)
+
+**All glow effects in Light theme = `none`:**
+
+```css
+--metric-default-glow: none;
+--metric-secondary-glow: none;
+--metric-success-glow: none;
+--metric-warning-glow: none;
+--metric-destructive-glow: none;
+/* ... and 9 more */
+```
+
+#### C. Glow Pattern Duplication
+
+**Glass theme:** All glows use `0 0 12px <color> / 0.4` pattern
+
+```css
+--metric-default-glow: 0 0 12px oklch(70.7% 0.143 250 / 0.4);
+--metric-success-glow: 0 0 12px oklch(76.5% 0.147 163 / 0.4);
+--metric-warning-glow: 0 0 12px oklch(82.8% 0.157 84 / 0.4);
+--metric-destructive-glow: 0 0 12px oklch(71.2% 0.161 12 / 0.4);
+```
+
+**Aurora theme:** All glows use `0 0 10px <color> / 0.35` pattern (except secondary:
+`0 0 8px / 0.25`)
+
+```css
+--metric-default-glow: 0 0 10px oklch(70.7% 0.143 250 / 0.35);
+--metric-success-glow: 0 0 10px oklch(76.5% 0.147 163 / 0.35);
+--metric-warning-glow: 0 0 10px oklch(82.8% 0.157 84 / 0.35);
+--metric-destructive-glow: 0 0 10px oklch(71.5% 0.179 27 / 0.35);
+```
+
+---
+
+## 💡 Optimization Recommendations
+
+### Priority 1: Remove Unused Variables ⚠️
+
+**Investigate if these `transparent` variables are actually used:**
+
+If `--metric-*-bg` and `--metric-*-border` are never used (always transparent), they can be removed
+entirely:
+
+```css
+/* Can be removed if unused: */
+--metric-default-bg: transparent; /* Used anywhere? */
+--metric-default-border: transparent; /* Used anywhere? */
+--metric-success-bg: transparent; /* Used anywhere? */
+--metric-success-border: transparent; /* Used anywhere? */
+/* ... etc */
+```
+
+**Action:** Search codebase for usage of these variables. If unused, remove from all themes.
+
+**Potential savings:** ~16 variables × 3 themes = 48 variable definitions
+
+---
+
+### Priority 2: Simplify Glow System 🎨
+
+**Current:** Each metric variant has its own glow variable with repeated patterns.
+
+**Proposal:** Use CSS functions or global glow intensity variables.
+
+#### Option A: Glow Intensity Tokens
+
+```css
+/* Global tokens (add to root or theme) */
+--glow-radius-sm: 8px;
+--glow-radius-md: 10px;
+--glow-radius-lg: 12px;
+--glow-opacity-light: 0.25;
+--glow-opacity-medium: 0.35;
+--glow-opacity-strong: 0.4;
+
+/* Then in themes: */
+[data-theme='glass'] {
+  --glow-radius: var(--glow-radius-lg); /* 12px */
+  --glow-opacity: var(--glow-opacity-strong); /* 0.4 */
+}
+
+[data-theme='aurora'] {
+  --glow-radius: var(--glow-radius-md); /* 10px */
+  --glow-opacity: var(--glow-opacity-medium); /* 0.35 */
+}
+
+[data-theme='light'] {
+  --glow-radius: 0;
+  --glow-opacity: 0;
+}
+
+/* Usage in metric variables: */
+--metric-success-glow: 0 0 var(--glow-radius) oklch(76.5% 0.147 163 / var(--glow-opacity));
+```
+
+**Savings:** Reduces pattern duplication, easier to adjust glow intensity globally.
+
+---
+
+### Priority 3: Consider Color Semantic Tokens 🎭
+
+**Current issue:** Text colors differ between Glass/Aurora and Light themes.
+
+**Example:**
+
+```css
+/* Glass/Aurora */
+--metric-success-text: oklch(76.5% 0.147 163); /* emerald-400 */
+
+/* Light */
+--metric-success-text: oklch(69.6% 0.155 163); /* emerald-500 */
+```
+
+**Proposal:** Use semantic lightness tokens:
+
+```css
+/* Root level */
+--color-lightness-for-dark: 76.5%; /* 400-level colors */
+--color-lightness-for-light: 69.6%; /* 500-level colors */
+
+/* Then: */
+[data-theme='glass'],
+[data-theme='aurora'] {
+  --base-lightness: var(--color-lightness-for-dark);
+}
+
+[data-theme='light'] {
+  --base-lightness: var(--color-lightness-for-light);
+}
+```
+
+**Note:** This is more complex and may not be worth it unless you plan many more themes.
+
+---
+
+### Priority 4: Audit Deprecated Aliases Removal Timeline 📅
+
+**Current status:** Deprecated aliases are defined but unused in codebase.
+
+**Recommendation:**
+
+1. **v1.x** - Keep deprecated aliases (current state) ✅
+2. **v2.0** - Add deprecation warnings to CHANGELOG
+3. **v2.1** - Add console warnings when deprecated variables are detected
+4. **v3.0** - Remove deprecated aliases entirely
+
+**Migration path for external consumers:**
+
+```md
+## Migration from v1.x to v2.x
+
+Replace all deprecated metric color variables:
+
+- `--metric-emerald-*` → `--metric-success-*`
+- `--metric-amber-*` → `--metric-warning-*`
+- `--metric-blue-*` → `--metric-default-*`
+- `--metric-red-*` → `--metric-destructive-*`
+```
+
+---
+
+## 🚀 Implementation Priority
+
+### High Priority (Do Now)
+
+1. ✅ **Verify deprecated aliases are unused** - DONE
+2. 🔍 **Search for unused `transparent` variables** - TODO
+3. 📝 **Document removal timeline** - Add to CHANGELOG
+
+### Medium Priority (Consider for v2.0)
+
+4. 🎨 **Simplify glow system** with intensity tokens
+5. 📦 **Remove unused transparent variables** (if found)
+6. 🔧 **Add deprecation notices** to CHANGELOG
+
+### Low Priority (Future)
+
+7. 🎭 **Consider semantic color tokens** (if adding 5+ themes)
+8. 🧹 **Remove deprecated aliases** in v3.0
+
+---
+
+## 📝 Action Items
+
+### Immediate
+
+- [ ] Search codebase for `--metric-*-bg` usage (bg variants)
+- [ ] Search codebase for `--metric-*-border` usage (border variants)
+- [ ] If unused, create PR to remove these variables from all themes
+
+### v2.0 Planning
+
+- [x] Add deprecation notice to CHANGELOG.md (see [CHANGELOG.md](../CHANGELOG.md#unreleased))
+- [ ] Update migration documentation
+- [ ] Consider glow system refactoring
+
+### v3.0 Planning
+
+- [ ] Remove all deprecated `--metric-emerald/amber/blue/red-*` aliases
+- [ ] Update documentation
+
+---
+
+## 📊 Metrics
+
+**Cleanup potential:**
+
+- Unused transparent variables: Up to 48 definitions (16 vars × 3 themes)
+- Deprecated aliases: 48 definitions (16 vars × 3 themes) - **keep for now**
+
+**Total potential reduction:** ~96 variable definitions if all transparent vars are unused
+
+**Actual impact:** Minimal - CSS variables are lightweight. Focus on:
+
+1. ✅ **Consistency** - Already achieved!
+2. 📚 **Maintainability** - Document removal timeline
+3. 🧹 **Cleanup** - Remove truly unused vars
+
+---
+
+## ✅ Conclusion
+
+**Current state: EXCELLENT**
+
+1. ✅ No deprecated variable usage in components
+2. ✅ Consistent naming convention (shadcn/ui compatible)
+3. ✅ All tests passing with new variables
+4. 📋 Some optimization opportunities (transparent vars, glow patterns)
+
+**Next steps:** Focus on Priority 1 (unused variable audit) and Priority 4 (deprecation timeline).

package/docs/CSS_VARIABLES_REFACTORING_PLAN.md

@@ -0,0 +1,330 @@
+# CSS Variables Refactoring Plan
+
+## Problem Statement
+
+Current state: **Massive color duplication** across 3 theme files (glass.css, light.css, aurora.css)
+
+| Theme  | Most Duplicated Color             | Usage Count |
+| ------ | --------------------------------- | ----------- |
+| Glass  | `oklch(66.6% 0.159 303)` (purple) | 33+ times   |
+| Light  | `oklch(54.1% 0.175 293)` (violet) | 28 times    |
+| Aurora | `oklch(62.7% 0.159 291)` (violet) | 20+ times   |
+
+Additional duplication:
+
+- White with various alphas: 40+ uses per theme
+- Semantic colors (success/warning/error): 12-16 uses each
+- Border colors: 15-24 uses per theme
+- Surface colors: 8-11 uses per theme
+
+**Total duplication**: ~70% of CSS variables are duplicated color values
+
+---
+
+## Proposed Architecture
+
+### Three-Layer System
+
+```
+┌─────────────────────────────────────────────┐
+│ Layer 3: Component Variables (unchanged)     │
+│ --btn-primary-bg, --input-border, etc.      │
+└─────────────────────────────────────────────┘
+                    ↓ references
+┌─────────────────────────────────────────────┐
+│ Layer 2: Semantic Tokens (NEW)              │
+│ --semantic-primary, --semantic-surface, etc. │
+└─────────────────────────────────────────────┘
+                    ↓ references
+┌─────────────────────────────────────────────┐
+│ Layer 1: Primitive Tokens (NEW)             │
+│ --primitive-purple-500, --primitive-white-08 │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Layer 1: Primitive Tokens (primitives.css)
+
+**Purpose**: Define raw color values once, reused by all themes
+
+```css
+/* primitives.css - NEW FILE */
+:root {
+  /* ============================================
+     PRIMITIVE COLOR TOKENS
+     Raw OKLCH values - DO NOT use directly
+     ============================================ */
+
+  /* Purple scale (glass theme primary) */
+  --primitive-purple-300: oklch(79.5% 0.103 293);
+  --primitive-purple-500: oklch(66.6% 0.159 303);
+  --primitive-violet-500: oklch(62.7% 0.159 291);
+  --primitive-violet-400: oklch(71.4% 0.138 291);
+
+  /* Light theme primary */
+  --primitive-violet-light-500: oklch(54.1% 0.175 293);
+
+  /* Semantic colors (shared across themes) */
+  --primitive-emerald-400: oklch(76.5% 0.147 163);
+  --primitive-amber-400: oklch(82.8% 0.157 84);
+  --primitive-rose-400: oklch(71.2% 0.161 12);
+  --primitive-blue-400: oklch(70.7% 0.143 250);
+
+  /* Neutral scale */
+  --primitive-white: oklch(100% 0 0);
+  --primitive-black: oklch(0% 0 0);
+  --primitive-neutral-900: oklch(27.9% 0.041 260);
+  --primitive-neutral-800: oklch(37.2% 0.044 257);
+  --primitive-neutral-700: oklch(55.4% 0.046 257);
+  --primitive-neutral-200: oklch(92.9% 0.013 255);
+  --primitive-neutral-100: oklch(96.8% 0.007 247);
+
+  /* ============================================
+     ALPHA UTILITIES
+     For creating opacity variants
+     ============================================ */
+  --alpha-05: 0.05;
+  --alpha-08: 0.08;
+  --alpha-10: 0.1;
+  --alpha-15: 0.15;
+  --alpha-20: 0.2;
+  --alpha-25: 0.25;
+  --alpha-30: 0.3;
+  --alpha-40: 0.4;
+  --alpha-50: 0.5;
+  --alpha-60: 0.6;
+  --alpha-80: 0.8;
+  --alpha-90: 0.9;
+}
+```
+
+---
+
+## Layer 2: Semantic Tokens (in each theme file)
+
+**Purpose**: Theme-specific semantic mappings
+
+```css
+/* glass.css */
+[data-theme='glass'] {
+  /* ============================================
+     SEMANTIC COLOR TOKENS
+     Theme-agnostic names for component use
+     ============================================ */
+
+  /* Primary accent */
+  --semantic-primary: var(--primitive-purple-500);
+  --semantic-primary-muted: oklch(from var(--primitive-purple-500) l c h / var(--alpha-30));
+  --semantic-primary-subtle: oklch(from var(--primitive-purple-500) l c h / var(--alpha-20));
+  --semantic-primary-text: var(--primitive-purple-300);
+
+  /* Secondary accent */
+  --semantic-secondary: var(--primitive-violet-500);
+
+  /* Surfaces */
+  --semantic-surface: oklch(from var(--primitive-white) l c h / var(--alpha-08));
+  --semantic-surface-subtle: oklch(from var(--primitive-white) l c h / var(--alpha-05));
+  --semantic-surface-medium: oklch(from var(--primitive-white) l c h / var(--alpha-15));
+  --semantic-surface-strong: oklch(from var(--primitive-white) l c h / var(--alpha-22));
+
+  /* Borders */
+  --semantic-border: oklch(from var(--primitive-white) l c h / var(--alpha-15));
+  --semantic-border-subtle: oklch(from var(--primitive-white) l c h / var(--alpha-10));
+  --semantic-border-strong: oklch(from var(--primitive-white) l c h / var(--alpha-25));
+
+  /* Text */
+  --semantic-text: oklch(from var(--primitive-white) l c h / var(--alpha-90));
+  --semantic-text-muted: oklch(from var(--primitive-white) l c h / var(--alpha-60));
+  --semantic-text-subtle: oklch(from var(--primitive-white) l c h / var(--alpha-50));
+  --semantic-text-disabled: oklch(from var(--primitive-white) l c h / var(--alpha-30));
+
+  /* Semantic states (shared across themes) */
+  --semantic-success: var(--primitive-emerald-400);
+  --semantic-warning: var(--primitive-amber-400);
+  --semantic-error: var(--primitive-rose-400);
+  --semantic-info: var(--primitive-blue-400);
+}
+```
+
+---
+
+## Layer 3: Component Variables (existing)
+
+**No changes needed** - component variables reference semantic tokens:
+
+```css
+/* BEFORE (current) */
+--btn-primary-bg: linear-gradient(135deg, oklch(66.6% 0.159 303), oklch(62.7% 0.159 291));
+--stepper-step-completed-bg: oklch(66.6% 0.159 303);
+
+/* AFTER (refactored) */
+--btn-primary-bg: linear-gradient(135deg, var(--semantic-primary), var(--semantic-secondary));
+--stepper-step-completed-bg: var(--semantic-primary);
+```
+
+---
+
+## Modern CSS Features Used
+
+### 1. `oklch(from ...)` Relative Color Syntax
+
+```css
+/* Create alpha variants from base color */
+--semantic-primary-muted: oklch(from var(--primitive-purple-500) l c h / 0.3);
+```
+
+**Browser support**: Chrome 119+, Safari 16.4+, Firefox 128+ (2024)
+
+**Fallback strategy**: Define explicit values for older browsers
+
+### 2. CSS Custom Property Composition
+
+```css
+--semantic-surface: oklch(from var(--primitive-white) l c h / var(--alpha-08));
+```
+
+---
+
+## Migration Strategy
+
+### Phase 1: Foundation (Week 1)
+
+- ✅ Create `src/styles/primitives.css`
+- ✅ Define all primitive tokens
+- ✅ Import in main CSS entry point
+- ✅ Add semantic tokens to glass.css
+
+### Phase 2: Glass Theme Refactor (Week 2)
+
+- Refactor all component variables in glass.css
+- Replace hardcoded OKLCH with semantic token references
+- Test visual appearance (no regressions)
+- Run Storybook visual tests
+
+### Phase 3: Light Theme Refactor (Week 3)
+
+- Add semantic tokens to light.css
+- Refactor component variables
+- Test visual appearance
+
+### Phase 4: Aurora Theme Refactor (Week 4)
+
+- Add semantic tokens to aurora.css
+- Refactor component variables
+- Test visual appearance
+
+### Phase 5: Cleanup & Documentation (Week 5)
+
+- Remove old `--color-*` tokens (replaced by `--semantic-*`)
+- Update documentation
+- Add migration guide for consumers
+- Performance testing
+
+---
+
+## Expected Benefits
+
+| Metric              | Before     | After      | Improvement             |
+| ------------------- | ---------- | ---------- | ----------------------- |
+| Unique color values | ~120       | ~30        | **75% reduction**       |
+| Lines of CSS        | ~1500      | ~800       | **47% reduction**       |
+| Theme file size     | ~500 lines | ~250 lines | **50% reduction**       |
+| Maintenance burden  | High       | Low        | Easier to change colors |
+| New theme creation  | 500 lines  | 50 lines   | **90% faster**          |
+
+---
+
+## Risk Assessment
+
+### Low Risk
+
+- ✅ No breaking changes to public API
+- ✅ Component variables stay the same
+- ✅ Only internal implementation changes
+
+### Medium Risk
+
+- ⚠️ Browser compatibility (`oklch(from ...)` requires modern browsers)
+- ⚠️ Visual testing needed to catch subtle color shifts
+
+### Mitigation
+
+- Provide fallback for older browsers using explicit OKLCH values
+- Run full visual regression suite on all 3 themes
+- Document browser requirements in README
+
+---
+
+## File Structure
+
+```
+src/styles/
+├── primitives.css          # NEW - Primitive color tokens
+├── themes/
+│   ├── glass.css           # MODIFIED - Semantic tokens + component vars
+│   ├── light.css           # MODIFIED - Semantic tokens + component vars
+│   └── aurora.css          # MODIFIED - Semantic tokens + component vars
+└── utilities/
+    └── glass-effects.css   # Existing blur/backdrop utilities
+```
+
+---
+
+## Example: Before & After
+
+### BEFORE (glass.css - current)
+
+```css
+/* 33+ duplicates of this color */
+--btn-primary-bg: linear-gradient(135deg, oklch(66.6% 0.159 303), oklch(62.7% 0.159 291));
+--btn-primary-glow: 0 0 30px oklch(66.6% 0.159 303 / 0.6);
+--checkbox-checked-bg: oklch(66.6% 0.159 303);
+--tab-active-bg: oklch(66.6% 0.159 303 / 0.2);
+--stepper-step-completed-bg: oklch(66.6% 0.159 303);
+--modal-glow: 0 0 60px oklch(66.6% 0.159 303 / 0.35);
+--slider-thumb-border: oklch(66.6% 0.159 303);
+/* ... 26 more uses ... */
+```
+
+### AFTER (glass.css - refactored)
+
+```css
+/* Semantic tokens (once) */
+--semantic-primary: var(--primitive-purple-500);
+--semantic-primary-muted: oklch(from var(--semantic-primary) l c h / 0.3);
+--semantic-primary-subtle: oklch(from var(--semantic-primary) l c h / 0.2);
+
+/* Component variables (reference semantic tokens) */
+--btn-primary-bg: linear-gradient(135deg, var(--semantic-primary), var(--semantic-secondary));
+--btn-primary-glow: 0 0 30px var(--semantic-primary-glow);
+--checkbox-checked-bg: var(--semantic-primary);
+--tab-active-bg: var(--semantic-primary-subtle);
+--stepper-step-completed-bg: var(--semantic-primary);
+--modal-glow: 0 0 60px var(--semantic-primary-glow);
+--slider-thumb-border: var(--semantic-primary);
+```
+
+**Result**: 33 duplicates → 1 definition, 32 references
+
+---
+
+## Next Steps
+
+1. **Review & Approve** this plan
+2. **Create primitives.css** with all base tokens
+3. **Refactor glass.css** (most complex theme)
+4. **Test thoroughly** (visual regression suite)
+5. **Refactor light.css & aurora.css**
+6. **Document** for contributors
+
+---
+
+## Open Questions
+
+1. Should we use `oklch(from ...)` syntax or define explicit alpha variants?
+   - **Recommendation**: Use explicit variants for better browser support
+2. Keep `--color-*` tokens or rename to `--semantic-*`?
+   - **Recommendation**: Rename to `--semantic-*` for clarity
+3. Should primitives.css be imported automatically or manually?
+   - **Recommendation**: Import in main glass-theme.css for automatic inclusion