shadcn-glass-ui 1.0.10 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (216) hide show
  1. package/CHANGELOG.md +259 -16
  2. package/README.md +248 -28
  3. package/context7.json +58 -0
  4. package/dist/cli/index.cjs +470 -0
  5. package/dist/cli/index.cjs.map +1 -0
  6. package/dist/cli/index.d.ts +18 -0
  7. package/dist/cli/index.js +469 -0
  8. package/dist/cli/index.js.map +1 -0
  9. package/dist/components.cjs +4 -4
  10. package/dist/components.d.ts +153 -22
  11. package/dist/components.js +2 -2
  12. package/dist/hooks.cjs +2 -2
  13. package/dist/index.cjs +872 -5
  14. package/dist/index.cjs.map +1 -1
  15. package/dist/index.d.ts +0 -2390
  16. package/dist/index.js +844 -3
  17. package/dist/index.js.map +1 -1
  18. package/dist/r/ai-card-glass.json +5 -12
  19. package/dist/r/avatar-glass.json +5 -15
  20. package/dist/r/circular-metric-glass.json +5 -11
  21. package/dist/r/circular-progress-glass.json +5 -12
  22. package/dist/r/combobox-glass.json +5 -13
  23. package/dist/r/flag-alert-glass.json +5 -11
  24. package/dist/r/flags-section-glass.json +5 -12
  25. package/dist/r/insight-card-glass.json +17 -0
  26. package/dist/r/interactive-card.json +5 -12
  27. package/dist/r/language-bar-glass.json +5 -11
  28. package/dist/r/metric-card-glass.json +6 -13
  29. package/dist/r/metrics-grid-glass.json +5 -11
  30. package/dist/r/modal-glass.json +5 -15
  31. package/dist/r/popover-glass.json +1 -1
  32. package/dist/r/progress-glass.json +5 -13
  33. package/dist/r/registry.json +20 -2
  34. package/dist/r/segmented-control-glass.json +5 -11
  35. package/dist/r/sparkline-glass.json +17 -0
  36. package/dist/r/stepper-glass.json +33 -0
  37. package/dist/r/tabs-glass.json +4 -9
  38. package/dist/r/trust-score-card-glass.json +5 -12
  39. package/dist/r/year-card-glass.json +5 -13
  40. package/dist/shadcn-glass-ui.css +1 -1
  41. package/dist/{theme-context-XtasSxRT.cjs → theme-context-CVW50BKW.cjs} +2 -2
  42. package/dist/{theme-context-XtasSxRT.cjs.map → theme-context-CVW50BKW.cjs.map} +1 -1
  43. package/dist/themes.cjs +1 -1
  44. package/dist/trust-score-card-glass-BcZbul0P.js +26895 -0
  45. package/dist/trust-score-card-glass-BcZbul0P.js.map +1 -0
  46. package/dist/trust-score-card-glass-r3qM09Jp.cjs +27689 -0
  47. package/dist/trust-score-card-glass-r3qM09Jp.cjs.map +1 -0
  48. package/dist/{use-focus-BbpE2qGq.cjs → use-focus-ZE8ozmZE.cjs} +2 -2
  49. package/dist/{use-focus-BbpE2qGq.cjs.map → use-focus-ZE8ozmZE.cjs.map} +1 -1
  50. package/dist/{use-wallpaper-tint-CIqtoETa.cjs → use-wallpaper-tint-BuS80tbN.cjs} +2 -2
  51. package/dist/{use-wallpaper-tint-CIqtoETa.cjs.map → use-wallpaper-tint-BuS80tbN.cjs.map} +1 -1
  52. package/dist/{utils-CGCOTvxT.js → utils-CcyeqpKQ.js} +1 -1
  53. package/dist/{utils-CGCOTvxT.js.map → utils-CcyeqpKQ.js.map} +1 -1
  54. package/dist/{utils-CriE74ig.cjs → utils-DLXayspX.cjs} +2 -2
  55. package/dist/{utils-CriE74ig.cjs.map → utils-DLXayspX.cjs.map} +1 -1
  56. package/dist/utils.cjs +1 -1
  57. package/dist/utils.js +1 -1
  58. package/docs/AI_IMPROVEMENTS_COMPLETE.md +574 -0
  59. package/docs/AI_USAGE.md +1328 -0
  60. package/docs/API_PATTERNS_COMPARISON.md +418 -0
  61. package/docs/BEST_PRACTICES.md +800 -0
  62. package/docs/COMPLIANCE_CHECKLIST.md +307 -0
  63. package/docs/COMPLIANCE_TESTING.md +436 -0
  64. package/docs/COMPONENTS_CATALOG.md +1076 -0
  65. package/docs/CSS_VARIABLES_AUDIT.md +306 -0
  66. package/docs/CSS_VARIABLES_REFACTORING_PLAN.md +330 -0
  67. package/docs/EXPORTS_MAP.json +875 -0
  68. package/docs/EXPORTS_STRUCTURE.md +729 -0
  69. package/docs/GETTING_STARTED.md +655 -0
  70. package/docs/METRIC_CARD_API_REDESIGN.md +354 -0
  71. package/docs/PRIMITIVE_MAPPING.md +404 -0
  72. package/docs/PUBLISHING.md +593 -0
  73. package/docs/REGISTRY_SUMMARY.md +96 -0
  74. package/docs/REGISTRY_USAGE.md +339 -0
  75. package/docs/SECURITY.md +117 -0
  76. package/docs/THEME_CREATION_GUIDE.md +455 -0
  77. package/docs/TOKEN_ARCHITECTURE.md +365 -0
  78. package/docs/announcements/v1.0.5-devto.md +363 -0
  79. package/docs/announcements/v1.0.5-reddit.md +115 -0
  80. package/docs/announcements/v1.0.5-twitter.md +70 -0
  81. package/docs/api/README.md +725 -0
  82. package/docs/api/functions/ThemeProvider.md +21 -0
  83. package/docs/api/functions/cn.md +27 -0
  84. package/docs/api/functions/getNextTheme.md +21 -0
  85. package/docs/api/functions/getThemeConfig.md +21 -0
  86. package/docs/api/functions/useFocus.md +53 -0
  87. package/docs/api/functions/useHover.md +47 -0
  88. package/docs/api/functions/useResponsive.md +31 -0
  89. package/docs/api/functions/useTheme.md +15 -0
  90. package/docs/api/functions/useWallpaperTint.md +36 -0
  91. package/docs/api/globals.md +139 -0
  92. package/docs/api/interfaces/AlertGlassProps.md +131 -0
  93. package/docs/api/interfaces/AvatarGlassProps.md +114 -0
  94. package/docs/api/interfaces/BadgeGlassProps.md +118 -0
  95. package/docs/api/interfaces/ButtonGlassProps.md +179 -0
  96. package/docs/api/interfaces/CheckboxGlassProps.md +125 -0
  97. package/docs/api/interfaces/DropdownGlassProps.md +123 -0
  98. package/docs/api/interfaces/DropdownItem.md +53 -0
  99. package/docs/api/interfaces/GlassCardProps.md +151 -0
  100. package/docs/api/interfaces/InputGlassProps.md +169 -0
  101. package/docs/api/interfaces/NotificationGlassProps.md +67 -0
  102. package/docs/api/interfaces/ProgressGlassProps.md +49 -0
  103. package/docs/api/interfaces/SkeletonGlassProps.md +41 -0
  104. package/docs/api/interfaces/SliderGlassProps.md +107 -0
  105. package/docs/api/interfaces/TabItem.md +25 -0
  106. package/docs/api/interfaces/ThemeConfig.md +25 -0
  107. package/docs/api/interfaces/ThemeContextValue.md +47 -0
  108. package/docs/api/interfaces/ToggleGlassProps.md +59 -0
  109. package/docs/api/interfaces/TooltipGlassProps.md +119 -0
  110. package/docs/api/type-aliases/AlertType.md +11 -0
  111. package/docs/api/type-aliases/AlertVariant.md +11 -0
  112. package/docs/api/type-aliases/AvatarSize.md +11 -0
  113. package/docs/api/type-aliases/AvatarStatus.md +13 -0
  114. package/docs/api/type-aliases/BadgeSize.md +11 -0
  115. package/docs/api/type-aliases/BadgeVariant.md +11 -0
  116. package/docs/api/type-aliases/ButtonGlassSize.md +11 -0
  117. package/docs/api/type-aliases/ButtonGlassVariant.md +11 -0
  118. package/docs/api/type-aliases/DropdownAlign.md +11 -0
  119. package/docs/api/type-aliases/GlowType.md +11 -0
  120. package/docs/api/type-aliases/InputGlassSize.md +11 -0
  121. package/docs/api/type-aliases/IntensityType.md +11 -0
  122. package/docs/api/type-aliases/ModalSize.md +11 -0
  123. package/docs/api/type-aliases/NotificationType.md +11 -0
  124. package/docs/api/type-aliases/PaddingType.md +11 -0
  125. package/docs/api/type-aliases/ProgressGradient.md +11 -0
  126. package/docs/api/type-aliases/ProgressSize.md +11 -0
  127. package/docs/api/type-aliases/SkeletonVariant.md +11 -0
  128. package/docs/api/type-aliases/Theme.md +11 -0
  129. package/docs/api/type-aliases/ToggleGlassSize.md +11 -0
  130. package/docs/api/type-aliases/TooltipPosition.md +11 -0
  131. package/docs/api/variables/AICardGlass.md +11 -0
  132. package/docs/api/variables/AlertGlass.md +11 -0
  133. package/docs/api/variables/AvatarGlass.md +11 -0
  134. package/docs/api/variables/BadgeGlass.md +11 -0
  135. package/docs/api/variables/BaseProgressGlass.md +11 -0
  136. package/docs/api/variables/ButtonGlass.md +11 -0
  137. package/docs/api/variables/CareerStatsGlass.md +11 -0
  138. package/docs/api/variables/CareerStatsHeaderGlass.md +11 -0
  139. package/docs/api/variables/CheckboxGlass.md +11 -0
  140. package/docs/api/variables/CircularMetricGlass.md +22 -0
  141. package/docs/api/variables/CircularProgressGlass.md +11 -0
  142. package/docs/api/variables/ComboBoxGlass.md +27 -0
  143. package/docs/api/variables/ContributionMetricsGlass.md +11 -0
  144. package/docs/api/variables/DropdownGlass.md +11 -0
  145. package/docs/api/variables/ExpandableHeaderGlass.md +11 -0
  146. package/docs/api/variables/FlagAlertGlass.md +11 -0
  147. package/docs/api/variables/FlagsSectionGlass.md +11 -0
  148. package/docs/api/variables/FormFieldWrapper.md +44 -0
  149. package/docs/api/variables/GlassCard.md +11 -0
  150. package/docs/api/variables/HeaderBrandingGlass.md +11 -0
  151. package/docs/api/variables/HeaderNavGlass.md +11 -0
  152. package/docs/api/variables/IconButtonGlass.md +11 -0
  153. package/docs/api/variables/InputGlass.md +11 -0
  154. package/docs/api/variables/InteractiveCard.md +45 -0
  155. package/docs/api/variables/LanguageBarGlass.md +11 -0
  156. package/docs/api/variables/MetricCardGlass.md +11 -0
  157. package/docs/api/variables/MetricsGridGlass.md +11 -0
  158. package/docs/api/variables/ModalGlass.md +72 -0
  159. package/docs/api/variables/NotificationGlass.md +11 -0
  160. package/docs/api/variables/PopoverGlass.md +11 -0
  161. package/docs/api/variables/ProfileAvatarGlass.md +11 -0
  162. package/docs/api/variables/ProfileHeaderGlass.md +11 -0
  163. package/docs/api/variables/ProgressGlass.md +11 -0
  164. package/docs/api/variables/ProjectsListGlass.md +11 -0
  165. package/docs/api/variables/RainbowProgressGlass.md +11 -0
  166. package/docs/api/variables/RepositoryCardGlass.md +11 -0
  167. package/docs/api/variables/RepositoryHeaderGlass.md +11 -0
  168. package/docs/api/variables/RepositoryMetadataGlass.md +11 -0
  169. package/docs/api/variables/SearchBoxGlass.md +11 -0
  170. package/docs/api/variables/SegmentedControlGlass.md +11 -0
  171. package/docs/api/variables/SkeletonGlass.md +11 -0
  172. package/docs/api/variables/SliderGlass.md +11 -0
  173. package/docs/api/variables/SortDropdownGlass.md +11 -0
  174. package/docs/api/variables/StatItemGlass.md +11 -0
  175. package/docs/api/variables/StatusIndicatorGlass.md +11 -0
  176. package/docs/api/variables/THEMES.md +11 -0
  177. package/docs/api/variables/THEME_CONFIG.md +11 -0
  178. package/docs/api/variables/TabsGlass.md +52 -0
  179. package/docs/api/variables/ThemeToggleGlass.md +11 -0
  180. package/docs/api/variables/ToggleGlass.md +11 -0
  181. package/docs/api/variables/TooltipGlass.md +11 -0
  182. package/docs/api/variables/TouchTarget.md +35 -0
  183. package/docs/api/variables/TrustScoreCardGlass.md +11 -0
  184. package/docs/api/variables/TrustScoreDisplayGlass.md +11 -0
  185. package/docs/api/variables/UserInfoGlass.md +11 -0
  186. package/docs/api/variables/UserStatsLineGlass.md +11 -0
  187. package/docs/api/variables/YearCardGlass.md +11 -0
  188. package/docs/api/variables/alertVariants.md +21 -0
  189. package/docs/api/variables/avatarSizes.md +21 -0
  190. package/docs/api/variables/badgeVariants.md +21 -0
  191. package/docs/api/variables/buttonGlassVariants.md +21 -0
  192. package/docs/api/variables/cardIntensity.md +21 -0
  193. package/docs/api/variables/dropdownAlign.md +21 -0
  194. package/docs/api/variables/inputVariants.md +21 -0
  195. package/docs/api/variables/modalSizes.md +21 -0
  196. package/docs/api/variables/notificationVariants.md +21 -0
  197. package/docs/api/variables/progressSizes.md +21 -0
  198. package/docs/api/variables/shadcnAlertVariants.md +21 -0
  199. package/docs/api/variables/shadcnBadgeVariants.md +21 -0
  200. package/docs/api/variables/shadcnButtonVariants.md +21 -0
  201. package/docs/api/variables/skeletonVariants.md +21 -0
  202. package/docs/api/variables/statusSizes.md +21 -0
  203. package/docs/api/variables/toggleSizes.md +21 -0
  204. package/docs/api/variables/tooltipPositions.md +21 -0
  205. package/docs/design-system/UI_DESIGN.md +628 -0
  206. package/docs/migration/CSS_VARIABLES_MIGRATION_2.0.md +325 -0
  207. package/docs/migration/modal-glass-compound-api.md +458 -0
  208. package/docs/migration/select-to-combobox.md +386 -0
  209. package/docs/migration/tabs-glass-compound-api.md +579 -0
  210. package/docs/technical/DEPENDENCIES.md +291 -0
  211. package/docs/visual-testing-guide.md +324 -0
  212. package/package.json +16 -3
  213. package/dist/trust-score-card-glass-CNcQveNY.cjs +0 -8231
  214. package/dist/trust-score-card-glass-CNcQveNY.cjs.map +0 -1
  215. package/dist/trust-score-card-glass-CowcDyxH.js +0 -7795
  216. package/dist/trust-score-card-glass-CowcDyxH.js.map +0 -1
package/README.md CHANGED
@@ -11,22 +11,31 @@
11
11
  [![AI-Friendly](https://img.shields.io/badge/AI-Friendly-blueviolet?logo=openai)](docs/AI_USAGE.md)
12
12
  [![Claude Code](https://img.shields.io/badge/Claude-Code-5865F2?logo=anthropic)](docs/AI_USAGE.md)
13
13
  [![GitHub Copilot](https://img.shields.io/badge/GitHub-Copilot-181717?logo=github)](docs/AI_USAGE.md)
14
+ [![Context7](https://img.shields.io/badge/Context7-Indexed-00D4AA)](https://context7.com/yhooi2/shadcn-glass-ui-library)
14
15
 
15
- Glassmorphism UI library for React - AI-friendly with 55+ components, strict TypeScript, and comprehensive docs.
16
+ Glassmorphism UI library for React - AI-friendly with 58 components, strict TypeScript, and
17
+ comprehensive docs.
16
18
 
17
19
  ## ✨ Highlights
18
20
 
19
- - 🎨 **55 Components** - Core UI (18) + Atomic (6) + Composite (13) + Sections (7) + Specialized (8) + Primitives (3)
21
+ - 🎨 **58 Components** - Core UI (18) + Atomic (7) + Composite (13) + Sections (7) + Specialized
22
+ (10) + Primitives (3)
23
+ - 🪜 **StepperGlass** - NEW compound stepper component with 3 variants (numbered, icon, dots)
20
24
  - 🌈 **3 Themes** - Glass (dark glassmorphism), Light (clean minimal), Aurora (gradient glow)
25
+ - 🎨 **3-Layer Token System** - 207 primitive tokens, zero hardcoded colors, 15-minute theme
26
+ creation
21
27
  - 🤖 **AI-Friendly** - Optimized for Claude Code, Copilot, GPT with comprehensive docs
22
- - 🔮 **Advanced Patterns** - asChild polymorphic rendering, Compound components (Modal, Tabs)
28
+ - 🔮 **Advanced Patterns** - asChild polymorphic rendering, Compound components (Modal, Tabs,
29
+ Stepper)
23
30
  - ♿ **WCAG 2.1 AA** - Full accessibility compliance with automated testing
24
31
  - 📱 **Touch Optimized** - 44×44px minimum touch targets (Apple HIG)
25
32
  - ⚡ **Modern Stack** - React 19, Tailwind v4, Vitest 4, Storybook 10, Vite 7
26
- - 🧪 **1355+ Tests** - 650+ compliance + 580 visual regression + 125 unit tests
33
+ - 🧪 **~1570+ Tests** - 650+ compliance + 802 visual regression + 125 unit tests
27
34
  - 📦 **shadcn Compatible** - Works seamlessly with existing shadcn/ui projects
28
- - 🎯 **Design System** - Comprehensive [UI_DESIGN.md](docs/design-system/UI_DESIGN.md) specifications
35
+ - 🎯 **Design System** - Comprehensive [UI_DESIGN.md](docs/design-system/UI_DESIGN.md)
36
+ specifications
29
37
  - 📦 **Bundle Size** - ~110KB gzipped (production build)
38
+ - 📊 **Data Visualization** - SparklineGlass for compact time series, InsightCardGlass for analytics
30
39
 
31
40
  ## Tech Stack
32
41
 
@@ -39,32 +48,134 @@ Glassmorphism UI library for React - AI-friendly with 55+ components, strict Typ
39
48
 
40
49
  See [DEPENDENCIES.md](DEPENDENCIES.md) for detailed dependency documentation.
41
50
 
51
+ ## 🎨 Design System
52
+
53
+ - **Token Architecture** - [3-layer CSS token system](docs/TOKEN_ARCHITECTURE.md) with 207 OKLCH
54
+ primitives
55
+ - **Theme Creation** - Create production-ready themes in [15 minutes](docs/THEME_CREATION_GUIDE.md)
56
+ - **Zero Hardcoded Colors** - 100% CSS variable coverage across all components
57
+ - **Rapid Theming** - 90% faster theme creation (2-3 hours → 10-15 minutes)
58
+ - **Complete Documentation** - [CSS Variables Audit](docs/CSS_VARIABLES_AUDIT.md) with 296+
59
+ variables per theme
60
+ - **Migration Support** - [Automated migration tools](docs/migration/CSS_VARIABLES_MIGRATION_2.0.md)
61
+ for v2.0.0
62
+
42
63
  ## 🤖 AI Assistant Support
43
64
 
44
- This library is **optimized for AI coding assistants** including Claude Code, GitHub Copilot, and ChatGPT:
65
+ This library is **optimized for AI coding assistants** including Claude Code, GitHub Copilot, and
66
+ ChatGPT:
45
67
 
46
68
  - 📖 **Dedicated AI Guide** - [AI_USAGE.md](docs/AI_USAGE.md) with decision trees and workflows
47
69
  - 🎯 **TypeScript Strict Mode** - Full type inference for autocomplete
48
70
  - 📝 **Rich JSDoc** - Every component documented with @example, @accessibility
49
- - 🗂️ **Component Catalog** - [COMPONENTS_CATALOG.md](docs/COMPONENTS_CATALOG.md) with searchable index
71
+ - 🗂️ **Component Catalog** - [COMPONENTS_CATALOG.md](docs/COMPONENTS_CATALOG.md) with searchable
72
+ index
50
73
  - 🔍 **Exports Map** - Machine-readable [EXPORTS_MAP.json](docs/EXPORTS_MAP.json)
51
74
  - 🧪 **Real-World Examples** - Use-case based Storybook stories
52
- - 📦 **shadcn CLI Compatible** - Install components via `npx shadcn add @shadcn-glass-ui/button-glass`
75
+ - 📦 **shadcn CLI Compatible** - Install components via
76
+ `npx shadcn add @shadcn-glass-ui/button-glass`
77
+ - 🌐 **Context7 Indexed** - Discoverable via
78
+ [Context7 MCP](https://context7.com/yhooi2/shadcn-glass-ui-library) for AI assistants
79
+
80
+ [**→ Read AI Usage Guide**](docs/AI_USAGE.md) |
81
+ [**→ Component Catalog**](docs/COMPONENTS_CATALOG.md)
82
+
83
+ ## 🤖 AI Tools Integration
84
+
85
+ This library is indexed and optimized for multiple AI development tools:
86
+
87
+ - **[Context7](https://context7.com/yhooi2/shadcn-glass-ui-library)** - MCP server integration with
88
+ 59 AI-specific rules
89
+ - **Claude Code** - Optimized with [CLAUDE.md](CLAUDE.md) and project-specific instructions
90
+ - **GitHub Copilot** - TypeScript strict mode + comprehensive JSDoc annotations
91
+ - **ChatGPT/GPT-4** - Machine-readable [EXPORTS_MAP.json](docs/EXPORTS_MAP.json) with component
92
+ metadata
93
+
94
+ **Features for AI assistants:**
95
+
96
+ - 🎯 Decision trees for installation methods ([AI_USAGE.md](docs/AI_USAGE.md))
97
+ - 📋 59 Context7 rules covering breaking changes, compound APIs, token system
98
+ - 🔍 Searchable component catalog with fuzzy matching support
99
+ - 📦 Machine-readable exports with props, variants, and keywords
100
+ - 🧪 Test coverage metadata for quality assurance
101
+
102
+ ## 🖥️ CLI
53
103
 
54
- [**→ Read AI Usage Guide**](docs/AI_USAGE.md) | [**→ Component Catalog**](docs/COMPONENTS_CATALOG.md)
104
+ Explore components directly from the command line:
105
+
106
+ ```bash
107
+ # Get component info (fuzzy search supported)
108
+ npx shadcn-glass-ui info ButtonGlass
109
+ npx shadcn-glass-ui info button
110
+ npx shadcn-glass-ui info modal
111
+
112
+ # List all components
113
+ npx shadcn-glass-ui list
114
+
115
+ # List by category
116
+ npx shadcn-glass-ui list --category=core
117
+ npx shadcn-glass-ui list --category=composite
118
+
119
+ # Show help
120
+ npx shadcn-glass-ui --help
121
+ ```
55
122
 
56
123
  ## 📚 Documentation
57
124
 
58
- - **[Live Storybook](https://yhooi2.github.io/shadcn-glass-ui-library/)** - Interactive component demos
125
+ - **[Live Storybook](https://yhooi2.github.io/shadcn-glass-ui-library/)** - Interactive component
126
+ demos
59
127
  - **[npm Package](https://www.npmjs.com/package/shadcn-glass-ui)** - Public npm registry
128
+ - **[Registry Guide](docs/REGISTRY_USAGE.md)** - shadcn CLI installation via registry
60
129
  - **[Getting Started Guide](docs/GETTING_STARTED.md)** - Setup tutorial
61
130
  - **[GitHub](https://github.com/Yhooi2/shadcn-glass-ui-library)** - Source code
62
- - [Component Documentation](https://yhooi2.github.io/shadcn-glass-ui-library/?path=/docs) - Detailed API references
63
- - [Registry Usage Guide](docs/REGISTRY_USAGE.md) - shadcn CLI installation guide
131
+ - [Component Documentation](https://yhooi2.github.io/shadcn-glass-ui-library/?path=/docs) - Detailed
132
+ API references
64
133
  - [Design System](docs/design-system/UI_DESIGN.md) - Comprehensive UI specifications
65
134
  - [Migration Guides](docs/migration/) - Upgrade and API changes
66
135
 
67
- ## 📦 Installation
136
+ ## 📦 Installation Methods
137
+
138
+ shadcn-glass-ui can be installed in two ways:
139
+
140
+ ### Option 1: Registry (shadcn CLI) ⭐ Recommended
141
+
142
+ **Listed on [registry.directory](https://registry.directory)!**
143
+
144
+ Configure your `components.json`:
145
+
146
+ ```json
147
+ {
148
+ "registries": {
149
+ "@shadcn-glass-ui": {
150
+ "url": "https://raw.githubusercontent.com/Yhooi2/shadcn-glass-ui-library/main/public/r"
151
+ }
152
+ }
153
+ }
154
+ ```
155
+
156
+ Install components via shadcn CLI:
157
+
158
+ ```bash
159
+ # Single component
160
+ npx shadcn@latest add @shadcn-glass-ui/button-glass
161
+
162
+ # Multiple components
163
+ npx shadcn@latest add @shadcn-glass-ui/button-glass @shadcn-glass-ui/input-glass @shadcn-glass-ui/modal-glass
164
+
165
+ # With automatic dependencies
166
+ npx shadcn@latest add @shadcn-glass-ui/button-glass --deps
167
+ ```
168
+
169
+ **Benefits:**
170
+
171
+ - ✅ Automatic dependency installation
172
+ - ✅ Type-safe CLI workflow
173
+ - ✅ Compatible with existing shadcn/ui projects
174
+ - ✅ 58 components available
175
+
176
+ **[→ Full Registry Documentation](docs/REGISTRY_USAGE.md)**
177
+
178
+ ### Option 2: npm Package
68
179
 
69
180
  Install from npm registry:
70
181
 
@@ -72,9 +183,14 @@ Install from npm registry:
72
183
  npm install shadcn-glass-ui
73
184
  ```
74
185
 
186
+ **[→ npm Installation Guide](docs/GETTING_STARTED.md)**
187
+
188
+ ---
189
+
75
190
  ## 🚀 Quick Start
76
191
 
77
192
  **Requirements:**
193
+
78
194
  - React 18.0+ or 19.0+
79
195
  - React-DOM 18.0+ or 19.0+
80
196
  - Tailwind CSS 4.0+
@@ -169,9 +285,103 @@ import { ModalGlass, TabsGlass } from 'shadcn-glass-ui';
169
285
  </TabsGlass.Root>
170
286
  ```
171
287
 
288
+ ## ⚠️ Breaking Changes (v2.0.0)
289
+
290
+ **v2.0.0 removes deprecated CSS variables.** This is a major version bump due to breaking changes in
291
+ theming.
292
+
293
+ ### Removed CSS Variables
294
+
295
+ The following CSS variable names have been **REMOVED** in v2.0.0:
296
+
297
+ | Removed (v1.x) | Replacement (v2.0+) | Semantic Meaning |
298
+ | -------------------- | ------------------------ | --------------------------------- |
299
+ | `--metric-emerald-*` | `--metric-success-*` | Success states (positive metrics) |
300
+ | `--metric-amber-*` | `--metric-warning-*` | Warning states (attention needed) |
301
+ | `--metric-blue-*` | `--metric-default-*` | Neutral/default states |
302
+ | `--metric-red-*` | `--metric-destructive-*` | Error/danger states (critical) |
303
+
304
+ **Total removed:** 16 variables (4 color families × 4 properties each: bg, text, border, glow)
305
+
306
+ ### Why This Change?
307
+
308
+ - **Semantic Clarity**: Color names (emerald, amber, blue, red) → semantic roles (success, warning,
309
+ default, destructive)
310
+ - **shadcn/ui Compatibility**: Aligns with shadcn/ui variant naming conventions
311
+ - **Consistency**: Matches AlertGlass/BadgeGlass/ButtonGlass variant prop values
312
+ - **Token Architecture**: Part of the 3-layer token system migration
313
+
314
+ ### Migration Guide
315
+
316
+ **Automated Migration (Recommended):**
317
+
318
+ ```bash
319
+ # macOS/BSD
320
+ find src/ -type f \( -name "*.tsx" -o -name "*.ts" -o -name "*.css" \) -exec sed -i '' \
321
+ -e 's/--metric-emerald-/--metric-success-/g' \
322
+ -e 's/--metric-amber-/--metric-warning-/g' \
323
+ -e 's/--metric-blue-/--metric-default-/g' \
324
+ -e 's/--metric-red-/--metric-destructive-/g' \
325
+ {} +
326
+
327
+ # Linux
328
+ find src/ -type f \( -name "*.tsx" -o -name "*.ts" -o -name "*.css" \) -exec sed -i \
329
+ -e 's/--metric-emerald-/--metric-success-/g' \
330
+ -e 's/--metric-amber-/--metric-warning-/g' \
331
+ -e 's/--metric-blue-/--metric-default-/g' \
332
+ -e 's/--metric-red-/--metric-destructive-/g' \
333
+ {} +
334
+ ```
335
+
336
+ **Example:**
337
+
338
+ ```css
339
+ /* ❌ v1.x (REMOVED in v2.0) */
340
+ .metric-card-success {
341
+ background: var(--metric-emerald-bg);
342
+ color: var(--metric-emerald-text);
343
+ }
344
+
345
+ /* ✅ v2.0+ */
346
+ .metric-card-success {
347
+ background: var(--metric-success-bg);
348
+ color: var(--metric-success-text);
349
+ }
350
+ ```
351
+
352
+ **[→ Complete Migration Guide](docs/migration/CSS_VARIABLES_MIGRATION_2.0.md)** - Includes manual
353
+ examples, troubleshooting, and affected components.
354
+
355
+ ### New in v2.0.0
356
+
357
+ **Token Architecture:**
358
+
359
+ - **3-Layer System**: Primitive → Semantic → Component tokens
360
+ - **207 Primitive Tokens**: Complete OKLCH color palette in `oklch-primitives.css`
361
+ - **Zero Hardcoded Colors**: 100% migration to CSS variables (98→0 in glass.css)
362
+ - **Theme Creation**: 90% faster (2-3 hours → 10-15 minutes)
363
+
364
+ **New Components:**
365
+
366
+ - **StepperGlass** - Compound stepper with 3 variants (numbered, icon, dots), 2 orientations, linear
367
+ mode
368
+
369
+ **Custom Hooks (Exported):**
370
+
371
+ - `useFocus`, `useHover`, `useResponsive`, `useWallpaperTint`
372
+
373
+ **Documentation:**
374
+
375
+ - [TOKEN_ARCHITECTURE.md](docs/TOKEN_ARCHITECTURE.md) - Complete token system guide (365 lines)
376
+ - [THEME_CREATION_GUIDE.md](docs/THEME_CREATION_GUIDE.md) - Create themes in 15 minutes (455 lines)
377
+ - [CSS_VARIABLES_AUDIT.md](docs/CSS_VARIABLES_AUDIT.md) - Complete audit of 296+ variables per theme
378
+
379
+ ---
380
+
172
381
  ## ⚠️ Breaking Changes (v1.0.0)
173
382
 
174
- **v1.0.0 removes all legacy/deprecated APIs.** This is a clean slate release with only Compound API support.
383
+ **v1.0.0 removes all legacy/deprecated APIs.** This is a clean slate release with only Compound API
384
+ support.
175
385
 
176
386
  ### Removed Components
177
387
 
@@ -223,8 +433,10 @@ import { ModalGlass, TabsGlass } from 'shadcn-glass-ui';
223
433
  ```
224
434
 
225
435
  **Key Changes:**
436
+
226
437
  - `isOpen` → `open` (on ModalGlass.Root)
227
- - `onClose` → `onOpenChange` (callback signature changed from `() => void` to `(open: boolean) => void`)
438
+ - `onClose` → `onOpenChange` (callback signature changed from `() => void` to
439
+ `(open: boolean) => void`)
228
440
  - `title` prop removed → use `<ModalGlass.Title>` component
229
441
  - Manual structure required (Overlay, Content, Header, Body, Footer)
230
442
 
@@ -255,6 +467,7 @@ import { ModalGlass, TabsGlass } from 'shadcn-glass-ui';
255
467
  ```
256
468
 
257
469
  **Key Changes:**
470
+
258
471
  - `tabs` array prop removed → use individual `<TabsGlass.Trigger>` components
259
472
  - `activeTab` → `value` (on TabsGlass.Root)
260
473
  - `onChange` → `onValueChange`
@@ -300,7 +513,7 @@ Essential building blocks for any application:
300
513
 
301
514
  [View all Core UI components →](src/components/glass/ui/)
302
515
 
303
- ### Level 2: Atomic (6 components)
516
+ ### Level 2: Atomic (7 components)
304
517
 
305
518
  Small, specialized components for specific use cases:
306
519
 
@@ -310,6 +523,8 @@ Small, specialized components for specific use cases:
310
523
  - **SortDropdownGlass** - Sorting dropdown menu
311
524
  - **StatItemGlass** - Individual stat display
312
525
  - **IconButtonGlass** - Icon-only button variant
526
+ - **InsightCardGlass** - Insight display with 7 semantic variants (default, tip, highlight, warning,
527
+ stat, growth, decline)
313
528
 
314
529
  [View all Atomic components →](src/components/glass/atomic/)
315
530
 
@@ -333,7 +548,7 @@ Pre-built complex components combining multiple elements:
333
548
 
334
549
  [View all Composite components →](src/components/glass/composite/)
335
550
 
336
- ### Specialized Components (8 components)
551
+ ### Specialized Components (10 components)
337
552
 
338
553
  Advanced specialized components for specific use cases:
339
554
 
@@ -345,6 +560,8 @@ Advanced specialized components for specific use cases:
345
560
  - **FlagAlertGlass** - Warning/danger flag alert with icon
346
561
  - **ProgressGlass** - Enhanced progress bar
347
562
  - **BaseProgressGlass** - Base progress component
563
+ - **SparklineGlass** - Compact bar chart for time series visualization with height/gap variants
564
+ - **StepperGlass** - Compound stepper for multi-step workflows (numbered, icon, dots variants)
348
565
 
349
566
  [View all Specialized components →](src/components/glass/specialized/)
350
567
 
@@ -364,7 +581,8 @@ Full-page sections ready to use in your application:
364
581
 
365
582
  ### Blocks (6 ready-to-use demo sections)
366
583
 
367
- Complete component showcases following shadcn/ui pattern - these are demo/documentation components, not production-ready blocks:
584
+ Complete component showcases following shadcn/ui pattern - these are demo/documentation components,
585
+ not production-ready blocks:
368
586
 
369
587
  - **ButtonsBlock** - All button variants, sizes, states demo
370
588
  - **FormElementsBlock** - Input, Slider, Toggle, Checkbox demos
@@ -373,7 +591,8 @@ Complete component showcases following shadcn/ui pattern - these are demo/docume
373
591
  - **BadgesBlock** - Badge variants with tooltips demo
374
592
  - **NotificationsBlock** - Notifications and alerts demo
375
593
 
376
- **Note:** Blocks are showcase/demo components visible in Storybook. For production use, utilize individual components from the categories above.
594
+ **Note:** Blocks are showcase/demo components visible in Storybook. For production use, utilize
595
+ individual components from the categories above.
377
596
 
378
597
  [View Blocks in Storybook →](https://yhooi2.github.io/shadcn-glass-ui-library/?path=/story/glass-blocks--default)
379
598
 
@@ -381,7 +600,7 @@ Complete component showcases following shadcn/ui pattern - these are demo/docume
381
600
 
382
601
  Complete application examples showcasing all components:
383
602
 
384
- - **ComponentShowcase** - Interactive demo of all 55 components with theme switching
603
+ - **ComponentShowcase** - Interactive demo of all 58 components with theme switching
385
604
  - **DesktopShowcase** - GitHub Analytics desktop application mockup with glassmorphism design
386
605
  - **MobileShowcase** - Mobile-optimized GitHub profile view with responsive layout
387
606
 
@@ -491,6 +710,7 @@ GlassCard supports 3 intensity levels for customizable blur effects:
491
710
  ```
492
711
 
493
712
  **Intensity Levels:**
713
+
494
714
  - `subtle` - 8px blur (--blur-sm) - Light glass effect
495
715
  - `medium` - 16px blur (--blur-md) - Standard cards (default)
496
716
  - `strong` - 24px blur (--blur-lg) - Featured cards
@@ -552,14 +772,14 @@ Comprehensive test coverage across multiple layers:
552
772
  ### Test Suites
553
773
 
554
774
  ```bash
555
- # All tests (1,355+ total)
775
+ # All tests (~1,570+ total)
556
776
  npm test
557
777
 
558
778
  # Design system compliance (650+ tests)
559
779
  npm run test:compliance:run # jsdom tests
560
780
  npm run test:compliance:browser:run # browser tests
561
781
 
562
- # Visual regression (580 screenshots)
782
+ # Visual regression (802 screenshots)
563
783
  npm run test:visual:ci # Run visual tests
564
784
  npm run test:visual:update # Update baselines
565
785
 
@@ -572,12 +792,12 @@ npm run test:coverage
572
792
 
573
793
  ### Test Categories
574
794
 
575
- | Category | Tests | Coverage |
576
- | ---------------------------- | ---------- | ----------------- |
577
- | **Design System Compliance** | 650+ | 100% |
578
- | **Visual Regression** | 580 | All components |
579
- | **Unit Tests** | 125 | Core utilities |
580
- | **Total** | **1,355+** | **Comprehensive** |
795
+ | Category | Tests | Coverage |
796
+ | ---------------------------- | ----------- | ----------------- |
797
+ | **Design System Compliance** | 650+ | 100% |
798
+ | **Visual Regression** | 802 | All components |
799
+ | **Unit Tests** | 125 | Core utilities |
800
+ | **Total** | **~1,570+** | **Comprehensive** |
581
801
 
582
802
  ## 🛠️ Development
583
803
 
package/context7.json ADDED
@@ -0,0 +1,58 @@
1
+ {
2
+ "$schema": "https://context7.com/schema/context7.json",
3
+ "projectTitle": "shadcn-glass-ui",
4
+ "description": "Glassmorphism UI library for React - AI-friendly with 58 components, strict TypeScript, and comprehensive docs",
5
+ "branch": "main",
6
+ "folders": ["docs"],
7
+ "excludeFolders": ["src", "node_modules", "dist", ".storybook", ".github", "public", "coverage"],
8
+ "excludeFiles": ["package-lock.json", ".DS_Store"],
9
+ "rules": [
10
+ "Use 'variant' prop instead of 'type' for AlertGlass and NotificationGlass (v1.0 breaking change)",
11
+ "Use 'variant=\"destructive\"' instead of 'variant=\"danger\"' for ButtonGlass",
12
+ "Always wrap components with ThemeProvider from 'shadcn-glass-ui'",
13
+ "Import CSS: '@import \"shadcn-glass-ui/dist/styles.css\"' in main CSS file",
14
+ "Use TypeScript strict mode - no 'any' types allowed",
15
+ "ModalGlass and TabsGlass use compound component API (e.g., ModalGlass.Root, ModalGlass.Content)",
16
+ "Three themes available: 'glass' (dark), 'light', 'aurora' (gradient)",
17
+ "WCAG 2.1 AA accessibility compliance required",
18
+ "Use asChild prop on ButtonGlass for polymorphic rendering: <ButtonGlass asChild><Link href='/'>Home</Link></ButtonGlass>",
19
+ "Combine FormFieldWrapper with InputGlass for consistent form validation feedback",
20
+ "Use ComboBoxGlass instead of SelectGlass for searchable dropdowns (SelectGlass removed in v1.0)",
21
+ "For forms with validation, use InputGlass error/success props: <InputGlass error='Required' /> or <InputGlass success='Valid' />",
22
+ "Use SegmentedControlGlass for exclusive selection (like radio buttons but glass-styled)",
23
+ "Test all components with 3 themes before shipping: glass (dark), light, aurora",
24
+ "Use CSS variables from glass-theme.css for custom styling: --glass-bg, --blur-md, --focus-glow",
25
+ "Prefer GlassCard intensity variants (subtle, medium, strong) for different visual depths",
26
+ "Use TooltipGlass with aria-label on icon buttons for screen reader support",
27
+ "ExpandableHeaderGlass has built-in ARIA attributes for accessible expandable sections",
28
+ "Memoize ComboBoxGlass options array with useMemo to prevent unnecessary re-renders",
29
+ "RainbowProgressGlass uses GPU-optimized animations with will-change for smooth performance",
30
+ "SparklineGlass displays compact time series data - use with sparklineData array of numbers (e.g., [10, 15, 12, 18, 20])",
31
+ "SparklineGlass supports height variants (sm/md/lg) and gap spacing (none/sm/md) for flexible visualization",
32
+ "InsightCardGlass has 7 semantic variants: default, tip, highlight, warning, stat, growth, decline",
33
+ "InsightCardGlass supports inline and card display modes - use displayMode prop to switch between layouts",
34
+ "YearCardGlass accepts optional sparklineData for monthly activity trends visualization",
35
+ "YearCardGlass accepts optional insights array for displaying InsightCardGlass items with all 7 variants",
36
+ "MetricCardGlass supports optional sparklineData for metric trend visualization alongside progress bars",
37
+ "When using sparklineData in cards, data array length should match your time period (e.g., 12 months = 12 values)",
38
+ "Use 3-layer token system: Primitive → Semantic → Component tokens (v2.0.0+)",
39
+ "NEVER hardcode OKLCH values - use CSS variables from oklch-primitives.css",
40
+ "For custom styling, use semantic tokens: var(--semantic-primary), var(--semantic-surface)",
41
+ "CSS variables removed in v2.0.0: --metric-emerald-*, --metric-amber-*, --metric-blue-*, --metric-red-*",
42
+ "Use new semantic names: --metric-success-*, --metric-warning-*, --metric-default-*, --metric-destructive-*",
43
+ "Create new themes in 15 minutes using THEME_CREATION_GUIDE.md template",
44
+ "All 207 primitive tokens defined in src/styles/tokens/oklch-primitives.css",
45
+ "Reference TOKEN_ARCHITECTURE.md for complete token system documentation",
46
+ "StepperGlass component uses compound API: StepperGlass.Root, .Step, .Title, .Description, .Indicator",
47
+ "StepperGlass has 3 variants: numbered (default), icon, dots - use variant prop",
48
+ "StepperGlass orientation: horizontal (default) or vertical",
49
+ "StepperGlass supports linear mode (wizard pattern) - set linear prop to lock future steps",
50
+ "Use exported hooks: useFocus, useHover, useResponsive, useWallpaperTint for custom components"
51
+ ],
52
+ "previousVersions": [
53
+ { "tag": "v2.0.0", "title": "Version 2.0.0 (Latest - Token Architecture)" },
54
+ { "tag": "v1.1.0", "title": "Version 1.1.0" },
55
+ { "tag": "v1.0.11", "title": "Version 1.0.11" },
56
+ { "tag": "v1.0.0", "title": "Version 1.0.0 (Breaking Changes)" }
57
+ ]
58
+ }