shadcn-glass-ui 2.0.4 → 2.0.6

package/README.md

@@ -1,147 +1,45 @@
 # shadcn-glass-ui
 
-[![npm version](https://img.shields.io/npm/v/shadcn-glass-ui.svg)](https://www.npmjs.com/package/shadcn-glass-ui)
-[![npm downloads](https://img.shields.io/npm/dm/shadcn-glass-ui.svg)](https://www.npmjs.com/package/shadcn-glass-ui)
-[![License](https://img.shields.io/npm/l/shadcn-glass-ui.svg)](https://github.com/Yhooi2/shadcn-glass-ui-library/blob/main/LICENSE)
-[![CI](https://github.com/Yhooi2/shadcn-glass-ui-library/workflows/CI%2FCD%20Pipeline/badge.svg)](https://github.com/Yhooi2/shadcn-glass-ui-library/actions)
-[![Bundle Size](https://img.shields.io/bundlephobia/minzip/shadcn-glass-ui)](https://bundlephobia.com/package/shadcn-glass-ui)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
-[![React](https://img.shields.io/badge/React-19.2-blue)](https://reactjs.org/)
-[![Tailwind CSS](https://img.shields.io/badge/Tailwind-4.1-blue)](https://tailwindcss.com/)
-[![AI-Friendly](https://img.shields.io/badge/AI-Friendly-blueviolet?logo=openai)](docs/AI_USAGE.md)
-[![Claude Code](https://img.shields.io/badge/Claude-Code-5865F2?logo=anthropic)](docs/AI_USAGE.md)
-[![GitHub Copilot](https://img.shields.io/badge/GitHub-Copilot-181717?logo=github)](docs/AI_USAGE.md)
-[![Context7](https://img.shields.io/badge/Context7-Indexed-00D4AA)](https://context7.com/yhooi2/shadcn-glass-ui-library)
-
-Glassmorphism UI library for React - AI-friendly with 58 components, strict TypeScript, and
-comprehensive docs.
-
-## ✨ Highlights
-
-- 🎨 **58 Components** - Core UI (18) + Atomic (7) + Composite (13) + Sections (7) + Specialized
-  (10) + Primitives (3)
-- 🪜 **StepperGlass** - NEW compound stepper component with 3 variants (numbered, icon, dots)
-- 🌈 **3 Themes** - Glass (dark glassmorphism), Light (clean minimal), Aurora (gradient glow)
-- 🎨 **3-Layer Token System** - 207 primitive tokens, zero hardcoded colors, 15-minute theme
-  creation
-- 🤖 **AI-Friendly** - Optimized for Claude Code, Copilot, GPT with comprehensive docs
-- 🔮 **Advanced Patterns** - asChild polymorphic rendering, Compound components (Modal, Tabs,
-  Stepper)
-- ♿ **WCAG 2.1 AA** - Full accessibility compliance with automated testing
-- 📱 **Touch Optimized** - 44×44px minimum touch targets (Apple HIG)
-- ⚡ **Modern Stack** - React 19, Tailwind v4, Vitest 4, Storybook 10, Vite 7
-- 🧪 **~1570+ Tests** - 650+ compliance + 802 visual regression + 125 unit tests
-- 📦 **shadcn Compatible** - Works seamlessly with existing shadcn/ui projects
-- 🎯 **Design System** - Comprehensive [UI_DESIGN.md](docs/design-system/UI_DESIGN.md)
-  specifications
-- 📦 **Bundle Size** - ~110KB gzipped (production build)
-- 📊 **Data Visualization** - SparklineGlass for compact time series, InsightCardGlass for analytics
-
-## Tech Stack
-
-- **React 19.2** - Server Components, React Compiler, automatic batching
-- **TypeScript 5.9** - Strict type checking
-- **Tailwind CSS 4.1** - CSS-first configuration with CSS variables
-- **Vite 7** (rolldown-vite) - Rust-powered bundler
-- **Storybook 10.1** - Component workshop with ESM-only architecture
-- **Vitest 4.0** - Browser mode testing with visual regression
-
-See [DEPENDENCIES.md](DEPENDENCIES.md) for detailed dependency documentation.
-
-## 🎨 Design System
-
-- **Token Architecture** - [3-layer CSS token system](docs/TOKEN_ARCHITECTURE.md) with 207 OKLCH
-  primitives
-- **Theme Creation** - Create production-ready themes in [15 minutes](docs/THEME_CREATION_GUIDE.md)
-- **Zero Hardcoded Colors** - 100% CSS variable coverage across all components
-- **Rapid Theming** - 90% faster theme creation (2-3 hours → 10-15 minutes)
-- **Complete Documentation** - [CSS Variables Audit](docs/CSS_VARIABLES_AUDIT.md) with 296+
-  variables per theme
-- **Migration Support** - [Automated migration tools](docs/migration/CSS_VARIABLES_MIGRATION_2.0.md)
-  for v2.0.0
-
-## 🤖 AI Assistant Support
-
-This library is **optimized for AI coding assistants** including Claude Code, GitHub Copilot, and
-ChatGPT:
-
-- 📖 **Dedicated AI Guide** - [AI_USAGE.md](docs/AI_USAGE.md) with decision trees and workflows
-- 🎯 **TypeScript Strict Mode** - Full type inference for autocomplete
-- 📝 **Rich JSDoc** - Every component documented with @example, @accessibility
-- 🗂️ **Component Catalog** - [COMPONENTS_CATALOG.md](docs/COMPONENTS_CATALOG.md) with searchable
-  index
-- 🔍 **Exports Map** - Machine-readable [EXPORTS_MAP.json](docs/EXPORTS_MAP.json)
-- 🧪 **Real-World Examples** - Use-case based Storybook stories
-- 📦 **shadcn CLI Compatible** - Install components via
-  `npx shadcn add @shadcn-glass-ui/button-glass`
-- 🌐 **Context7 Indexed** - Discoverable via
-  [Context7 MCP](https://context7.com/yhooi2/shadcn-glass-ui-library) for AI assistants
-
-[**→ Read AI Usage Guide**](docs/AI_USAGE.md) |
-[**→ Component Catalog**](docs/COMPONENTS_CATALOG.md)
-
-## 🤖 AI Tools Integration
-
-This library is indexed and optimized for multiple AI development tools:
-
-- **[Context7](https://context7.com/yhooi2/shadcn-glass-ui-library)** - MCP server integration with
-  59 AI-specific rules
-- **Claude Code** - Optimized with [CLAUDE.md](CLAUDE.md) and project-specific instructions
-- **GitHub Copilot** - TypeScript strict mode + comprehensive JSDoc annotations
-- **ChatGPT/GPT-4** - Machine-readable [EXPORTS_MAP.json](docs/EXPORTS_MAP.json) with component
-  metadata
-
-**Features for AI assistants:**
-
-- 🎯 Decision trees for installation methods ([AI_USAGE.md](docs/AI_USAGE.md))
-- 📋 59 Context7 rules covering breaking changes, compound APIs, token system
-- 🔍 Searchable component catalog with fuzzy matching support
-- 📦 Machine-readable exports with props, variants, and keywords
-- 🧪 Test coverage metadata for quality assurance
-
-## 🖥️ CLI
-
-Explore components directly from the command line:
+<div align="center">
 
-```bash
-# Get component info (fuzzy search supported)
-npx shadcn-glass-ui info ButtonGlass
-npx shadcn-glass-ui info button
-npx shadcn-glass-ui info modal
+![Glass Theme Preview](src/components/__visual__/__screenshots__/componentshowcase.visual.test.tsx/componentshowcase-full-glass-chromium.png)
 
-# List all components
-npx shadcn-glass-ui list
+**Glassmorphism UI components for React** — drop-in shadcn/ui compatible, AI-optimized
 
-# List by category
-npx shadcn-glass-ui list --category=core
-npx shadcn-glass-ui list --category=composite
+[Live Demo](https://yhooi2.github.io/shadcn-glass-ui-library/) |
+[Storybook](https://yhooi2.github.io/shadcn-glass-ui-library/) |
+[npm](https://www.npmjs.com/package/shadcn-glass-ui)
 
-# Show help
-npx shadcn-glass-ui --help
-```
+</div>
 
-## 📚 Documentation
+[![npm version](https://img.shields.io/npm/v/shadcn-glass-ui.svg)](https://www.npmjs.com/package/shadcn-glass-ui)
+[![npm downloads](https://img.shields.io/npm/dm/shadcn-glass-ui.svg)](https://www.npmjs.com/package/shadcn-glass-ui)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
+[![AI-Friendly](https://img.shields.io/badge/AI-Optimized-blueviolet)](docs/AI_USAGE.md)
+
+---
+
+## At a Glance
 
-- **[Live Storybook](https://yhooi2.github.io/shadcn-glass-ui-library/)** - Interactive component
-  demos
-- **[npm Package](https://www.npmjs.com/package/shadcn-glass-ui)** - Public npm registry
-- **[Registry Guide](docs/REGISTRY_USAGE.md)** - shadcn CLI installation via registry
-- **[Getting Started Guide](docs/GETTING_STARTED.md)** - Setup tutorial
-- **[GitHub](https://github.com/Yhooi2/shadcn-glass-ui-library)** - Source code
-- [Component Documentation](https://yhooi2.github.io/shadcn-glass-ui-library/?path=/docs) - Detailed
-  API references
-- [Design System](docs/design-system/UI_DESIGN.md) - Comprehensive UI specifications
-- [Migration Guides](docs/migration/) - Upgrade and API changes
+| Feature           | Details                                                                                 |
+| ----------------- | --------------------------------------------------------------------------------------- |
+| **Components**    | 58 total: 18 Core + 7 Atomic + 13 Composite + 7 Section + 10 Specialized + 3 Primitives |
+| **Themes**        | Glass (dark), Light (clean), Aurora (gradient)                                          |
+| **Stack**         | React 19, TypeScript 5.9, Tailwind 4.1, Vite 7                                          |
+| **Testing**       | 1,570+ tests (802 visual + 650 compliance + 125 unit)                                   |
+| **AI Support**    | Optimized for Claude, Copilot, GPT — [AI Guide](docs/AI_USAGE.md)                       |
+| **Accessibility** | WCAG 2.1 AA, 44px touch targets, keyboard navigation                                    |
+| **Bundle Size**   | ~110KB gzipped                                                                          |
 
-## 📦 Installation Methods
+---
 
-shadcn-glass-ui can be installed in two ways:
+## Quick Start
 
-### Option 1: Registry (shadcn CLI) ⭐ Recommended
+### Option 1: shadcn CLI (Recommended)
 
-**Listed on [registry.directory](https://registry.directory)!**
+**For existing shadcn/ui projects.** Listed on [registry.directory](https://registry.directory).
 
-Configure your `components.json`:
+1. Add registry to `components.json`:
 
 ```json
 {
@@ -153,769 +51,230 @@ Configure your `components.json`:
 }
 ```
 
-Install components via shadcn CLI:
+2. Install components:
 
 ```bash
-# Single component
-npx shadcn@latest add @shadcn-glass-ui/button-glass
-
-# Multiple components
-npx shadcn@latest add @shadcn-glass-ui/button-glass @shadcn-glass-ui/input-glass @shadcn-glass-ui/modal-glass
-
-# With automatic dependencies
-npx shadcn@latest add @shadcn-glass-ui/button-glass --deps
+npx shadcn@latest add @shadcn-glass-ui/button-glass @shadcn-glass-ui/input-glass
 ```
 
-**Benefits:**
-
-- ✅ Automatic dependency installation
-- ✅ Type-safe CLI workflow
-- ✅ Compatible with existing shadcn/ui projects
-- ✅ 58 components available
-
-**[→ Full Registry Documentation](docs/REGISTRY_USAGE.md)**
+[Full Registry Guide](docs/REGISTRY_USAGE.md)
 
 ### Option 2: npm Package
 
-Install from npm registry:
+**For new projects.**
 
 ```bash
 npm install shadcn-glass-ui
 ```
 
-**[→ npm Installation Guide](docs/GETTING_STARTED.md)**
-
----
-
-## 🚀 Quick Start
-
-**Requirements:**
-
-- React 18.0+ or 19.0+
-- React-DOM 18.0+ or 19.0+
-- Tailwind CSS 4.0+
-
-### Basic Usage
-
 ```tsx
-import { ButtonGlass, InputGlass, ThemeProvider } from 'shadcn-glass-ui';
+import { ButtonGlass, ThemeProvider } from 'shadcn-glass-ui';
 import 'shadcn-glass-ui/dist/styles.css';
 
 function App() {
   return (
     <ThemeProvider defaultTheme="glass">
-      <div className="p-8 space-y-4">
-        <ButtonGlass variant="primary" size="lg">
-          Click me
-        </ButtonGlass>
-        <InputGlass placeholder="Enter text..." />
-      </div>
+      <ButtonGlass variant="primary">Click me</ButtonGlass>
     </ThemeProvider>
   );
 }
-
-export default App;
-```
-
-## 🆕 Advanced Features (Phase 3)
-
-### asChild Pattern
-
-Polymorphic rendering with Radix UI Slot - render components as any element:
-
-```tsx
-import { ButtonGlass } from 'shadcn-glass-ui';
-import { Link } from 'react-router-dom';
-
-// Render button as Link
-<ButtonGlass asChild>
-  <Link to="/profile">View Profile</Link>
-</ButtonGlass>
-
-// Render button as anchor
-<ButtonGlass asChild variant="primary">
-  <a href="https://example.com" target="_blank">
-    External Link
-  </a>
-</ButtonGlass>
-```
-
-**Supported components:** `ButtonGlass`, `AvatarGlass`, `GlassCard`
-
-### Compound Components
-
-Fine-grained composition for complex components:
-
-```tsx
-import { ModalGlass, TabsGlass } from 'shadcn-glass-ui';
-
-// ModalGlass Compound API
-<ModalGlass.Root open={open} onOpenChange={setOpen}>
-  <ModalGlass.Overlay />
-  <ModalGlass.Content>
-    <ModalGlass.Header>
-      <ModalGlass.Title>Confirm Action</ModalGlass.Title>
-      <ModalGlass.Description>
-        This action cannot be undone
-      </ModalGlass.Description>
-      <ModalGlass.Close />
-    </ModalGlass.Header>
-    <ModalGlass.Body>
-      <p>Content here...</p>
-    </ModalGlass.Body>
-    <ModalGlass.Footer>
-      <ButtonGlass onClick={() => setOpen(false)}>Cancel</ButtonGlass>
-      <ButtonGlass variant="primary">Confirm</ButtonGlass>
-    </ModalGlass.Footer>
-  </ModalGlass.Content>
-</ModalGlass.Root>
-
-// TabsGlass Compound API
-<TabsGlass.Root value={activeTab} onValueChange={setActiveTab}>
-  <TabsGlass.List>
-    <TabsGlass.Trigger value="tab1">Overview</TabsGlass.Trigger>
-    <TabsGlass.Trigger value="tab2">Analytics</TabsGlass.Trigger>
-  </TabsGlass.List>
-  <TabsGlass.Content value="tab1">
-    <p>Overview content</p>
-  </TabsGlass.Content>
-  <TabsGlass.Content value="tab2">
-    <p>Analytics content</p>
-  </TabsGlass.Content>
-</TabsGlass.Root>
-```
-
-## ⚠️ Breaking Changes (v2.0.0)
-
-**v2.0.0 removes deprecated CSS variables.** This is a major version bump due to breaking changes in
-theming.
-
-### Removed CSS Variables
-
-The following CSS variable names have been **REMOVED** in v2.0.0:
-
-| Removed (v1.x)       | Replacement (v2.0+)      | Semantic Meaning                  |
-| -------------------- | ------------------------ | --------------------------------- |
-| `--metric-emerald-*` | `--metric-success-*`     | Success states (positive metrics) |
-| `--metric-amber-*`   | `--metric-warning-*`     | Warning states (attention needed) |
-| `--metric-blue-*`    | `--metric-default-*`     | Neutral/default states            |
-| `--metric-red-*`     | `--metric-destructive-*` | Error/danger states (critical)    |
-
-**Total removed:** 16 variables (4 color families × 4 properties each: bg, text, border, glow)
-
-### Why This Change?
-
-- **Semantic Clarity**: Color names (emerald, amber, blue, red) → semantic roles (success, warning,
-  default, destructive)
-- **shadcn/ui Compatibility**: Aligns with shadcn/ui variant naming conventions
-- **Consistency**: Matches AlertGlass/BadgeGlass/ButtonGlass variant prop values
-- **Token Architecture**: Part of the 3-layer token system migration
-
-### Migration Guide
-
-**Automated Migration (Recommended):**
-
-```bash
-# macOS/BSD
-find src/ -type f \( -name "*.tsx" -o -name "*.ts" -o -name "*.css" \) -exec sed -i '' \
-  -e 's/--metric-emerald-/--metric-success-/g' \
-  -e 's/--metric-amber-/--metric-warning-/g' \
-  -e 's/--metric-blue-/--metric-default-/g' \
-  -e 's/--metric-red-/--metric-destructive-/g' \
-  {} +
-
-# Linux
-find src/ -type f \( -name "*.tsx" -o -name "*.ts" -o -name "*.css" \) -exec sed -i \
-  -e 's/--metric-emerald-/--metric-success-/g' \
-  -e 's/--metric-amber-/--metric-warning-/g' \
-  -e 's/--metric-blue-/--metric-default-/g' \
-  -e 's/--metric-red-/--metric-destructive-/g' \
-  {} +
-```
-
-**Example:**
-
-```css
-/* ❌ v1.x (REMOVED in v2.0) */
-.metric-card-success {
-  background: var(--metric-emerald-bg);
-  color: var(--metric-emerald-text);
-}
-
-/* ✅ v2.0+ */
-.metric-card-success {
-  background: var(--metric-success-bg);
-  color: var(--metric-success-text);
-}
 ```
 
-**[→ Complete Migration Guide](docs/migration/CSS_VARIABLES_MIGRATION_2.0.md)** - Includes manual
-examples, troubleshooting, and affected components.
-
-### New in v2.0.0
-
-**Token Architecture:**
-
-- **3-Layer System**: Primitive → Semantic → Component tokens
-- **207 Primitive Tokens**: Complete OKLCH color palette in `oklch-primitives.css`
-- **Zero Hardcoded Colors**: 100% migration to CSS variables (98→0 in glass.css)
-- **Theme Creation**: 90% faster (2-3 hours → 10-15 minutes)
-
-**New Components:**
-
-- **StepperGlass** - Compound stepper with 3 variants (numbered, icon, dots), 2 orientations, linear
-  mode
-
-**Custom Hooks (Exported):**
-
-- `useFocus`, `useHover`, `useResponsive`, `useWallpaperTint`
-
-**Documentation:**
-
-- [TOKEN_ARCHITECTURE.md](docs/TOKEN_ARCHITECTURE.md) - Complete token system guide (365 lines)
-- [THEME_CREATION_GUIDE.md](docs/THEME_CREATION_GUIDE.md) - Create themes in 15 minutes (455 lines)
-- [CSS_VARIABLES_AUDIT.md](docs/CSS_VARIABLES_AUDIT.md) - Complete audit of 296+ variables per theme
+[Getting Started Guide](docs/GETTING_STARTED.md)
 
 ---
 
-## ⚠️ Breaking Changes (v1.0.0)
-
-**v1.0.0 removes all legacy/deprecated APIs.** This is a clean slate release with only Compound API
-support.
-
-### Removed Components
-
-#### SelectGlass (Removed in v1.0.0)
-
-**SelectGlass has been removed.** Use **ComboBoxGlass** instead.
-
-```tsx
-// ❌ Removed in v1.0.0
-<SelectGlass
-  options={options}
-  value={value}
-  onChange={setValue}
-  placeholder="Select option"
-/>
-
-// ✅ Use ComboBoxGlass
-<ComboBoxGlass
-  options={options}
-  value={value}
-  onChange={setValue}
-  placeholder="Select option"
-/>
-```
-
-### Removed Legacy APIs
-
-#### ModalGlass: Legacy Props API Removed
-
-**The old props-based API has been removed.** Use Compound API instead.
-
-```tsx
-// ❌ Removed in v1.0.0
-<ModalGlass isOpen={true} onClose={() => {}} title="Test">
-  Content
-</ModalGlass>
-
-// ✅ Use Compound API
-<ModalGlass.Root open={true} onOpenChange={() => {}}>
-  <ModalGlass.Overlay />
-  <ModalGlass.Content>
-    <ModalGlass.Header>
-      <ModalGlass.Title>Test</ModalGlass.Title>
-      <ModalGlass.Close />
-    </ModalGlass.Header>
-    <ModalGlass.Body>Content</ModalGlass.Body>
-  </ModalGlass.Content>
-</ModalGlass.Root>
-```
-
-**Key Changes:**
-
-- `isOpen` → `open` (on ModalGlass.Root)
-- `onClose` → `onOpenChange` (callback signature changed from `() => void` to
-  `(open: boolean) => void`)
-- `title` prop removed → use `<ModalGlass.Title>` component
-- Manual structure required (Overlay, Content, Header, Body, Footer)
-
-#### TabsGlass: Legacy Props API Removed
-
-**The old props-based API has been removed.** Use Compound API instead.
-
-```tsx
-// ❌ Removed in v1.0.0
-<TabsGlass
-  tabs={[
-    { id: 'tab1', label: 'Tab 1' },
-    { id: 'tab2', label: 'Tab 2' }
-  ]}
-  activeTab="tab1"
-  onChange={setActiveTab}
-/>
-
-// ✅ Use Compound API
-<TabsGlass.Root value="tab1" onValueChange={setActiveTab}>
-  <TabsGlass.List>
-    <TabsGlass.Trigger value="tab1">Tab 1</TabsGlass.Trigger>
-    <TabsGlass.Trigger value="tab2">Tab 2</TabsGlass.Trigger>
-  </TabsGlass.List>
-  <TabsGlass.Content value="tab1">Content 1</TabsGlass.Content>
-  <TabsGlass.Content value="tab2">Content 2</TabsGlass.Content>
-</TabsGlass.Root>
-```
-
-**Key Changes:**
-
-- `tabs` array prop removed → use individual `<TabsGlass.Trigger>` components
-- `activeTab` → `value` (on TabsGlass.Root)
-- `onChange` → `onValueChange`
-- Content must be explicitly defined with `<TabsGlass.Content>` for each tab
-
-### Migration Guides
-
-Detailed migration guides are available in the [docs/migration/](docs/migration/) directory:
+## Components
 
-- **[ModalGlass Compound API](docs/migration/modal-glass-compound-api.md)** - Legacy → Compound API
-- **[TabsGlass Compound API](docs/migration/tabs-glass-compound-api.md)** - Legacy → Compound API
+| Core UI                                                                                                                              | Composite                                                                                                        | Specialized                                                                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| ![Buttons](src/components/__visual__/__screenshots__/componentshowcase.visual.test.tsx/componentshowcase-buttons-glass-chromium.png) | ![Metrics](src/components/__visual__/__screenshots__/desktop.visual.test.tsx/desktop-ai-card-glass-chromium.png) | ![Progress](src/components/__visual__/__screenshots__/componentshowcase.visual.test.tsx/componentshowcase-progress-glass-chromium.png) |
+| ButtonGlass, InputGlass, ModalGlass, TabsGlass...                                                                                    | MetricCardGlass, AICardGlass, YearCardGlass...                                                                   | SparklineGlass, StepperGlass, RainbowProgressGlass...                                                                                  |
 
-### Changelog
+[View All 58 Components](docs/COMPONENTS_CATALOG.md) |
+[Interactive Storybook](https://yhooi2.github.io/shadcn-glass-ui-library/)
 
-See [CHANGELOG.md](CHANGELOG.md) for complete version history and breaking changes.
-
-## 📚 Full Documentation
-
-- **[Getting Started Guide](docs/GETTING_STARTED.md)** - Comprehensive setup tutorial
-- **[AI Usage Guide](docs/AI_USAGE.md)** - Using library with AI assistants (Copilot, Claude, GPT)
-- **[Publishing Guide](docs/PUBLISHING.md)** - Build and publish with TypeScript declarations
-- **[Storybook](https://yhooi2.github.io/shadcn-glass-ui-library/)** - Live component demos
-- **[UI Design System](docs/design-system/UI_DESIGN.md)** - Complete design specifications
-- **[Visual Testing Guide](docs/visual-testing-guide.md)** - Screenshot update workflow
-- **[Migration Guide](MIGRATION_GUIDE.md)** - Upgrading from v1
-- **[Breaking Changes](BREAKING_CHANGES.md)** - API changes log
-- **[Dependencies](DEPENDENCIES.md)** - Detailed dependency docs
-- **[Contributing](CONTRIBUTING.md)** - Development guidelines
-
-## 🎯 Component Categories
-
-### Level 1: Core UI (18 components)
-
-Essential building blocks for any application:
-
-- **Buttons & Actions**: ButtonGlass
-- **Inputs**: InputGlass, CheckboxGlass, ToggleGlass, SliderGlass, ComboBoxGlass, PopoverGlass
-- **Containers**: GlassCard, ModalGlass
-- **Navigation**: TabsGlass, DropdownGlass
-- **Feedback**: BadgeGlass, AlertGlass, NotificationGlass, TooltipGlass, SkeletonGlass,
-  ProgressGlass, CircularProgressGlass
-- **Media**: AvatarGlass
-
-[View all Core UI components →](src/components/glass/ui/)
-
-### Level 2: Atomic (7 components)
-
-Small, specialized components for specific use cases:
-
-- **SearchBoxGlass** - Search input with icon
-- **ThemeToggleGlass** - Theme switcher button
-- **ExpandableHeaderGlass** - Collapsible header section
-- **SortDropdownGlass** - Sorting dropdown menu
-- **StatItemGlass** - Individual stat display
-- **IconButtonGlass** - Icon-only button variant
-- **InsightCardGlass** - Insight display with 7 semantic variants (default, tip, highlight, warning,
-  stat, growth, decline)
-
-[View all Atomic components →](src/components/glass/atomic/)
-
-### Level 3: Composite (13 components)
-
-Pre-built complex components combining multiple elements:
-
-- **AICardGlass** - AI summary card with feature list
-- **MetricCardGlass** - Metric display card with progress indicator
-- **YearCardGlass** - Year card for career timeline
-- **CircularMetricGlass** - Circular progress metric display
-- **RepositoryCardGlass** - Repository card with expandable details
-- **RepositoryHeaderGlass** - Repository header with metadata
-- **RepositoryMetadataGlass** - Repository metadata display
-- **TrustScoreDisplayGlass** - Trust score with visual indicator
-- **UserStatsLineGlass** - User statistics horizontal display
-- **UserInfoGlass** - User information card
-- **CareerStatsHeaderGlass** - Career statistics header
-- **ContributionMetricsGlass** - Contribution metrics display
-- **MetricsGridGlass** - Grid layout for metrics
-
-[View all Composite components →](src/components/glass/composite/)
-
-### Specialized Components (10 components)
-
-Advanced specialized components for specific use cases:
-
-- **StatusIndicatorGlass** - Status dots with glow effect
-- **SegmentedControlGlass** - Segmented button group
-- **RainbowProgressGlass** - Rainbow gradient progress bar
-- **LanguageBarGlass** - Language proficiency bar with legend
-- **ProfileAvatarGlass** - Large avatar with glow animation
-- **FlagAlertGlass** - Warning/danger flag alert with icon
-- **ProgressGlass** - Enhanced progress bar
-- **BaseProgressGlass** - Base progress component
-- **SparklineGlass** - Compact bar chart for time series visualization with height/gap variants
-- **StepperGlass** - Compound stepper for multi-step workflows (numbered, icon, dots variants)
-
-[View all Specialized components →](src/components/glass/specialized/)
-
-### Level 4: Sections (7 components)
-
-Full-page sections ready to use in your application:
-
-- **HeaderNavGlass** - Navigation header with search and theme toggle
-- **ProfileHeaderGlass** - User profile header with avatar, stats, and languages
-- **CareerStatsGlass** - Career statistics with expandable year cards
-- **FlagsSectionGlass** - Expandable flags/warnings section
-- **TrustScoreCardGlass** - Trust score display with detailed metrics
-- **ProjectsListGlass** - Projects list with filtering and sorting
-- **HeaderBrandingGlass** - Branded header with logo and navigation
-
-[View all Section components →](src/components/glass/sections/)
-
-### Blocks (6 ready-to-use demo sections)
-
-Complete component showcases following shadcn/ui pattern - these are demo/documentation components,
-not production-ready blocks:
-
-- **ButtonsBlock** - All button variants, sizes, states demo
-- **FormElementsBlock** - Input, Slider, Toggle, Checkbox demos
-- **ProgressBlock** - Progress bars, RainbowProgress, Skeletons demo
-- **AvatarGalleryBlock** - Avatar sizes and status indicators demo
-- **BadgesBlock** - Badge variants with tooltips demo
-- **NotificationsBlock** - Notifications and alerts demo
+---
 
-**Note:** Blocks are showcase/demo components visible in Storybook. For production use, utilize
-individual components from the categories above.
+## Why shadcn-glass-ui?
 
-[View Blocks in Storybook →](https://yhooi2.github.io/shadcn-glass-ui-library/?path=/story/glass-blocks--default)
+| Standard shadcn/ui | shadcn-glass-ui                                  |
+| ------------------ | ------------------------------------------------ |
+| Flat design        | Glassmorphism effects (blur, glow, transparency) |
+| Manual theming     | 3 built-in themes with token system              |
+| Basic components   | 58 components including analytics widgets        |
+| DIY accessibility  | WCAG 2.1 AA + touch targets out of the box       |
+| Generic docs       | AI-optimized documentation                       |
 
-### Demo Pages (3 full applications)
+**Seamless Integration:** Works alongside existing shadcn/ui components. Same patterns, same CLI.
 
-Complete application examples showcasing all components:
+---
 
-- **ComponentShowcase** - Interactive demo of all 58 components with theme switching
-- **DesktopShowcase** - GitHub Analytics desktop application mockup with glassmorphism design
-- **MobileShowcase** - Mobile-optimized GitHub profile view with responsive layout
+## Component Categories
 
-[Try live demos →](https://yhooi2.github.io/shadcn-glass-ui-library/)
+<details>
+<summary><strong>Core UI (18)</strong> — Essential building blocks</summary>
 
-## 🎨 Themes
+ButtonGlass, InputGlass, CheckboxGlass, ToggleGlass, SliderGlass, ModalGlass, TabsGlass,
+DropdownGlass, TooltipGlass, AlertGlass, NotificationGlass, BadgeGlass, AvatarGlass, GlassCard,
+ProgressGlass, CircularProgressGlass, SkeletonGlass, ComboBoxGlass
 
-shadcn-glass-ui provides three built-in themes:
+</details>
 
-### 🌑 Glass Theme (Dark Glassmorphism)
+<details>
+<summary><strong>Atomic (7)</strong> — Single-purpose components</summary>
 
-Default dark theme with frosted glass effects:
+IconButtonGlass, ThemeToggleGlass, SearchBoxGlass, SortDropdownGlass, StatItemGlass,
+ExpandableHeaderGlass, InsightCardGlass
 
-```tsx
-<div className="theme-glass">
-  <ButtonGlass>Glassmorphic Button</ButtonGlass>
-</div>
-```
+</details>
 
-**Features:**
+<details>
+<summary><strong>Composite (13)</strong> — Pre-built complex widgets</summary>
 
-- Backdrop blur: 16px (md)
-- Dark background with glass overlays
-- Purple gradient accents
-- Glow effects on hover/focus
+MetricCardGlass, YearCardGlass, AICardGlass, RepositoryCardGlass, TrustScoreDisplayGlass,
+CircularMetricGlass, UserStatsLineGlass, UserInfoGlass, CareerStatsHeaderGlass,
+ContributionMetricsGlass, MetricsGridGlass, RepositoryHeaderGlass, RepositoryMetadataGlass
 
-### ☀️ Light Theme
+</details>
 
-Clean, minimal light theme:
+<details>
+<summary><strong>Section (7)</strong> — Full page sections</summary>
 
-```tsx
-<div className="theme-light">
-  <ButtonGlass>Light Theme Button</ButtonGlass>
-</div>
-```
+HeaderNavGlass, ProfileHeaderGlass, CareerStatsGlass, FlagsSectionGlass, TrustScoreCardGlass,
+ProjectsListGlass, HeaderBrandingGlass
 
-**Features:**
+</details>
 
-- Subtle shadows instead of blur
-- White/gray color palette
-- Reduced opacity overlays
-- Crisp, modern aesthetic
+<details>
+<summary><strong>Specialized (10)</strong> — Advanced components</summary>
 
-### 🌈 Aurora Theme (Gradient)
+StatusIndicatorGlass, SegmentedControlGlass, RainbowProgressGlass, LanguageBarGlass,
+ProfileAvatarGlass, FlagAlertGlass, BaseProgressGlass, SparklineGlass, StepperGlass (compound API
+with 3 variants)
 
-Vibrant gradient theme with glow effects:
+</details>
 
-```tsx
-<div className="theme-aurora">
-  <ButtonGlass>Aurora Gradient Button</ButtonGlass>
-</div>
-```
+[Full Component Catalog](docs/COMPONENTS_CATALOG.md)
 
-**Features:**
+---
 
-- Multi-color gradients
-- Enhanced glow effects
-- Dynamic backgrounds
-- Eye-catching visuals
+## Themes
 
-### Theme Switching
+| Glass (Dark)                                                                                                                    | Light                                                                                                                           | Aurora                                                                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| ![Glass](src/components/__visual__/__screenshots__/componentshowcase.visual.test.tsx/componentshowcase-full-glass-chromium.png) | ![Light](src/components/__visual__/__screenshots__/componentshowcase.visual.test.tsx/componentshowcase-full-light-chromium.png) | ![Aurora](src/components/__visual__/__screenshots__/componentshowcase.visual.test.tsx/componentshowcase-full-aurora-chromium.png) |
+| Frosted glass effects                                                                                                           | Clean minimal                                                                                                                   | Gradient glow                                                                                                                     |
 
 ```tsx
-import { useState } from 'react';
-import { ThemeProvider, useTheme } from '@/lib/theme-context';
-
-function App() {
-  return (
-    <ThemeProvider defaultTheme="glass">
-      <YourApp />
-    </ThemeProvider>
-  );
-}
+import { ThemeProvider, useTheme } from 'shadcn-glass-ui';
 
 function ThemeSwitcher() {
-  const { theme, setTheme } = useTheme();
-
-  return (
-    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
-      <option value="glass">Glass (Dark)</option>
-      <option value="light">Light</option>
-      <option value="aurora">Aurora</option>
-    </select>
-  );
+  const { theme, cycleTheme, setTheme } = useTheme();
+  return <button onClick={cycleTheme}>Current: {theme}</button>;
 }
 ```
 
-## 🔮 Glass Effect Intensity
-
-GlassCard supports 3 intensity levels for customizable blur effects:
+[Theme Creation Guide](docs/THEME_CREATION_GUIDE.md) — Create custom themes in 15 minutes
 
-```tsx
-// Subtle glass effect (8px blur)
-<GlassCard intensity="subtle">
-  Subtle Effect
-</GlassCard>
-
-// Standard glassmorphism (16px blur - default)
-<GlassCard intensity="medium">
-  Standard Glass
-</GlassCard>
-
-// Strong glass effect (24px blur)
-<GlassCard intensity="strong">
-  Strong Effect
-</GlassCard>
-```
-
-**Intensity Levels:**
-
-- `subtle` - 8px blur (--blur-sm) - Light glass effect
-- `medium` - 16px blur (--blur-md) - Standard cards (default)
-- `strong` - 24px blur (--blur-lg) - Featured cards
-
-**Performance Note:** Use sparingly - limit to 2-3 glass elements per view for optimal performance.
-
-## ♿ Accessibility
-
-All components are WCAG 2.1 AA compliant:
-
-- ✅ **Keyboard Navigation** - Full Tab/Enter/Arrow key support
-- ✅ **Screen Readers** - Proper ARIA labels and roles
-- ✅ **Focus Indicators** - Visible focus rings (2px inner + 4px outer)
-- ✅ **Color Contrast** - Minimum 4.5:1 for text, 3:1 for UI
-- ✅ **Touch Targets** - 44×44px minimum (Apple HIG)
-- ✅ **Reduced Motion** - Respects `prefers-reduced-motion`
-
-### Automated Testing
-
-```bash
-npm run test:compliance        # Design system compliance (650+ tests)
-npm run test:compliance:browser # Browser-based a11y tests
-```
-
-## 📊 Performance
-
-Thanks to the modern stack:
-
-### Build Performance
-
-- **Production Builds**: 3-16x faster (Rolldown bundler)
-- **Memory Usage**: 100x reduction vs Webpack/Rollup
-- **Dev Server**: Near-instant start with Vite HMR
-- **CSS Builds**: 100x faster incremental builds (Tailwind v4)
+---
 
-### Runtime Performance
+## FAQ
 
-- **Render Optimization**: 32% fewer renders (React 19 compiler)
-- **Bundle Size**: Tree-shakeable ESM exports
-- **Code Splitting**: Automatic route-based splitting
-- **CSS Output**: Optimized purged CSS (~10KB gzipped)
+<details>
+<summary><strong>How do I migrate from v1.x to v2.0?</strong></summary>
 
-### Performance Benchmarks
+v2.0 renames CSS variables to semantic names. Run the automated migration:
 
 ```bash
-npm run benchmark  # Run performance benchmarks
+find src/ -type f \( -name "*.tsx" -o -name "*.css" \) -exec sed -i '' \
+  -e 's/--metric-emerald-/--metric-success-/g' \
+  -e 's/--metric-amber-/--metric-warning-/g' \
+  -e 's/--metric-blue-/--metric-default-/g' \
+  -e 's/--metric-red-/--metric-destructive-/g' {} +
 ```
 
-Example results:
-
-- ButtonGlass initial render: < 1ms
-- 100 component renders: < 50ms
-- Theme switching: < 100ms
-
-## 🧪 Testing
-
-Comprehensive test coverage across multiple layers:
-
-### Test Suites
+[Full Migration Guide](docs/BREAKING_CHANGES.md)
 
-```bash
-# All tests (~1,570+ total)
-npm test
-
-# Design system compliance (650+ tests)
-npm run test:compliance:run          # jsdom tests
-npm run test:compliance:browser:run  # browser tests
+</details>
 
-# Visual regression (802 screenshots)
-npm run test:visual:ci              # Run visual tests
-npm run test:visual:update          # Update baselines
+<details>
+<summary><strong>Does it work with existing shadcn/ui components?</strong></summary>
 
-# Unit tests (125 tests)
-npm run test:unit
+Yes! Glass components use the same patterns and can coexist with standard shadcn/ui components.
 
-# Coverage report (90% target)
-npm run test:coverage
-```
+</details>
 
-### Test Categories
+<details>
+<summary><strong>What are the requirements?</strong></summary>
 
-| Category                     | Tests       | Coverage          |
-| ---------------------------- | ----------- | ----------------- |
-| **Design System Compliance** | 650+        | 100%              |
-| **Visual Regression**        | 802         | All components    |
-| **Unit Tests**               | 125         | Core utilities    |
-| **Total**                    | **~1,570+** | **Comprehensive** |
+- React 18.0+ or 19.0+
+- Tailwind CSS 4.0+
+- Node.js 20.16+
 
-## 🛠️ Development
+</details>
 
-### Prerequisites
+<details>
+<summary><strong>How do I use with AI assistants?</strong></summary>
 
-- **Node.js**: 20.16+, 22.19+, or 24+
-- **npm**: Latest stable version
+See our [AI Usage Guide](docs/AI_USAGE.md) with decision trees for Claude, Copilot, and GPT. The
+library is indexed on [Context7](https://context7.com/yhooi2/shadcn-glass-ui-library).
 
-### Setup
+</details>
 
-```bash
-# Clone repository
-git clone https://github.com/Yhooi2/shadcn-glass-ui-library.git
-cd shadcn-glass-ui-library
+<details>
+<summary><strong>Where are the breaking changes documented?</strong></summary>
 
-# Install dependencies
-npm install
+- [BREAKING_CHANGES.md](docs/BREAKING_CHANGES.md) — Consolidated v1.0 and v2.0 changes
+- [CHANGELOG.md](CHANGELOG.md) — Complete version history
+- [Migration Guides](docs/migration/) — Step-by-step migration
 
-# Setup git hooks (prevents committing screenshots from non-Linux platforms)
-./scripts/setup-git-hooks.sh
+</details>
 
-# Start development
-npm run dev          # Vite dev server (port 5173)
-npm run storybook    # Storybook (port 6006)
-```
+---
 
-### Build
+## Documentation
 
-```bash
-npm run build              # TypeScript check + Vite build
-npm run build-storybook    # Build static Storybook
-```
+| Resource                                                       | Description                 |
+| -------------------------------------------------------------- | --------------------------- |
+| [Storybook](https://yhooi2.github.io/shadcn-glass-ui-library/) | Interactive component demos |
+| [Getting Started](docs/GETTING_STARTED.md)                     | Setup tutorial              |
+| [Component Catalog](docs/COMPONENTS_CATALOG.md)                | All 58 components           |
+| [AI Usage Guide](docs/AI_USAGE.md)                             | For Claude, Copilot, GPT    |
+| [Theme Guide](docs/THEME_CREATION_GUIDE.md)                    | Create custom themes        |
+| [Token Architecture](docs/TOKEN_ARCHITECTURE.md)               | 3-layer CSS token system    |
+| [Advanced Patterns](docs/ADVANCED_PATTERNS.md)                 | asChild, Compound APIs      |
+| [Breaking Changes](docs/BREAKING_CHANGES.md)                   | Migration guides            |
 
-### Linting
+## CLI
 
 ```bash
-npm run lint               # ESLint
-npm run format             # Prettier
-```
-
-## 📁 Project Structure
-
-```
-shadcn-glass-ui/
-├── src/
-│   ├── components/
-│   │   ├── glass/
-│   │   │   ├── ui/           # Core UI components (17)
-│   │   │   ├── atomic/       # Atomic components (6)
-│   │   │   ├── composite/    # Composite components (13)
-│   │   │   └── sections/     # Section components (7)
-│   │   ├── blocks/           # Ready-to-use blocks (6)
-│   │   ├── __visual__/       # Visual regression tests
-│   │   ├── ComponentShowcase.tsx
-│   │   └── DesktopShowcase.tsx
-│   ├── lib/
-│   │   ├── utils.ts          # cn() utility
-│   │   ├── theme-context.tsx # Theme provider
-│   │   ├── themeStyles.ts    # Theme definitions
-│   │   └── variants/         # CVA variants
-│   ├── styles/
-│   │   ├── tokens/           # Design tokens
-│   │   └── themes/           # Theme CSS
-│   └── test/
-│       ├── compliance/       # Compliance tests
-│       └── utils/            # Test utilities
-├── .storybook/               # Storybook config
-├── docs/                     # Documentation
-├── docs/design-system/UI_DESIGN.md  # Design system spec
-└── package.json
+npx shadcn-glass-ui info button    # Component info (fuzzy search)
+npx shadcn-glass-ui list           # List all components
+npx shadcn-glass-ui list --category=core  # Filter by category
 ```
 
-## 🤝 Contributing
-
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-### Quick Contribution Guide
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feat/amazing-component`
-3. Make your changes following our code standards
-4. Run tests: `npm run test:compliance:run`
-5. Commit with conventional commits: `feat(ui): add DatePickerGlass component`
-6. Push and create a Pull Request
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-
-## 📝 License
-
-MIT License
+---
 
-This project is open source under the MIT license. See [LICENSE](LICENSE) for details.
+## Contributing
 
-## 🙏 Credits
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Built with amazing open source projects:
+## License
 
-- [shadcn/ui](https://ui.shadcn.com/) - Design system foundation
-- [Radix UI](https://www.radix-ui.com/) - Unstyled accessible primitives
-- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework
-- [Vite](https://vitejs.dev/) - Next generation frontend tooling
-- [Storybook](https://storybook.js.org/) - Component workshop
-- [Vitest](https://vitest.dev/) - Blazing fast unit test framework
+MIT — See [LICENSE](LICENSE)
 
-## 🔗 Links
+## Credits
 
-- **NPM Package**: [shadcn-glass-ui](https://www.npmjs.com/package/shadcn-glass-ui)
-- **Documentation**: [Storybook](https://yhooi2.github.io/shadcn-glass-ui-library/)
-- **GitHub**: [shadcn-glass-ui-library](https://github.com/Yhooi2/shadcn-glass-ui-library)
-- **Issues**: [Report a bug](https://github.com/Yhooi2/shadcn-glass-ui-library/issues)
-- **Discussions**: [Community](https://github.com/Yhooi2/shadcn-glass-ui-library/discussions)
+Built with [shadcn/ui](https://ui.shadcn.com/), [Radix UI](https://www.radix-ui.com/),
+[Tailwind CSS](https://tailwindcss.com/), [Vite](https://vitejs.dev/)
 
-## ⭐ Star History
+---
 
-If you find this project useful, please consider giving it a star on GitHub!
+<div align="center">
 
-[![Star History Chart](https://api.star-history.com/svg?repos=Yhooi2/shadcn-glass-ui-library&type=Date)](https://star-history.com/#Yhooi2/shadcn-glass-ui-library&Date)
+**[Star on GitHub](https://github.com/Yhooi2/shadcn-glass-ui-library)** if you find this useful!
 
----
+[![Star History Chart](https://api.star-history.com/svg?repos=Yhooi2/shadcn-glass-ui-library&type=Date)](https://star-history.com/#Yhooi2/shadcn-glass-ui-library)
 
-**Made with ❤️ and glassmorphism**
+</div>