shadcn-glass-ui 2.3.0 → 2.3.2

package/docs/CSS_VARIABLES_AUDIT.md

@@ -1,306 +0,0 @@
-# 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

@@ -1,330 +0,0 @@
-# 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